Overview

SkyNet is a server-driven web framework for ASP.NET Core / .NET 10 and SQL Server, with vanilla JavaScript on the client — no SPA, no build step, no toolchain.

What SkyNet is

SkyNet is a middleware layer that sits between the ASP.NET Core pipeline and your application code. You write page classes in C#; the framework routes requests to them by class name, renders their HTML on the first request, and thereafter lets each method push surgical DOM mutations back to the browser.

The runtime consists of one assembly (SkyNet.dll) plus one client script (skynet.core.js) that the framework injects automatically. There is nothing to install on the client, nothing to compile on the front end, and no package manifest to maintain.

The core idea

An interaction never returns a new HTML page. The browser POSTs to a page method; the method returns a JSON list of DOM operations; a small client engine applies them in place.

That single object says: opcode 20 (set innerHTML), on the element with id result, to the markup in p1. The server never hands back a page and the client never decides what the page should look like. The server owns the DOM and pushes changes to it.

You never write that JSON by hand. You call builder methods on an ApiResponse object and the framework serializes the ops for you:

public async Task<ApiResponse> Save()
{
    ApiResponse response = new ApiResponse();
    response.SetElementContents("result", "<b>Saved</b>");
    return response;
}

This is the same family of idea as Hotwire Turbo Streams, Phoenix LiveView, and htmx — the server decides, the client applies. SkyNet arrived at it independently and implements it with no dependencies beyond the .NET runtime.

What it is not

• Not an SPA framework. There is no client-side router, no virtual DOM, no component tree, no client state store.
• Not a templating engine. There is no Razor, no view models bound to markup. HTML lives in .html files with {placeholder} tokens that the page class replaces, or is built server-side with string composition or ToolKit.
• Not an ORM. You write SQL. SQLData parameterizes and executes it; DataTableListT<T> maps results onto plain classes when you want typed rows.
• Not convention-over-configuration in the MVC sense. Routing is by class name resolved from the assembly, not by route table or attribute.

Why it suits AI-assisted development

SkyNet was shaped by, and for, a workflow in which a developer owns the architecture and database schema while an AI assistant generates most of the implementation. Several of its design choices are unusual in a hand-written codebase but are exactly what makes machine-generated code reliable here.

• Deliberate duplication over shared abstraction. Copying a block into a second page is preferred to extracting a helper. Abstraction saves keystrokes, which is the scarce resource for a human and the abundant one for an assistant; what it costs is locality, which is the scarce resource for both. A change to one page cannot break another.
• No build step, so no build-time failure modes. Generated code either compiles or does not. There is no bundler config, no transpile target, no module resolution to get wrong.
• Naming is the contract. Method names, element ids, CSS prefixes and placeholder tokens are all plain strings with a stated convention. An assistant can satisfy a convention stated in prose far more reliably than it can infer one from a framework's internals.
• The whole client API is flat and prefixed. Every client global begins with $. There is no import to resolve and no namespace to guess.
• Copy, retarget, adapt. Because pages do not share code, an existing page is a working template for the next one. "Build the Invoice page the way the Contact page works" is a complete and unambiguous instruction.

Products built on SkyNet

SkyNet underpins several shipped line-of-business products, among them ServiceNet (field-service management), SalesNet (order-to-cash ERP) and BizJournal (CRM / relationship journal). The conventions in this guide are drawn from those codebases; they are the house style, not framework requirements, except where marked REQUIRED.

How to read this guide

Request Lifecycle

Two paths, and only two. A GET builds and returns a whole document. Every interaction after that is a POST that returns DOM operations.

The two request paths. Shaded boxes are server-side; dark boxes are what the browser ends up with.

The GET render

A browser requests a page by name. SkyNet resolves the class from the executing assembly, instantiates it, runs the lifecycle hooks, and returns one complete HTML document.

1. Construct. The page class constructor runs. This is where Translation is switched on and the page dictionary is loaded (see Translation).
2. OnInit(type, func). Authentication and authorization. Returning a non-empty string stops the request with that message.
3. OnLoad(). Optional early hook.
4. OnInitialized(). The main body. Load data, build HTML fragments, replace {placeholder} tokens in HtmlDoc.HtmlBodyText, queue HtmlDoc.InitialScripts.
5. OnBeforeRender(). Last chance to alter the document.
6. Render. The framework assembles <head> and <body>, injects skynet.core.js, and auto-loads the page's own .js and .css by name.
7. OnAfterRender(). Post-processing on the finished document — this is where translation is applied.

The POST round trip

After the document is loaded, every interaction is an XHR POST that returns operations rather than markup.

1. A handler calls $ApiRequest('Save', data) (or $('Save'), or $Call('Save', 'k=v')).
2. The client builds FormData, appending the payload plus the standard envelope — timezone, URL params, page-scoped localStorage, and every form field on screen. See the POST envelope.
3. It POSTs to a URI derived from the current path: <area>/<Page>/<Method>.
4. Server-side, OnInit authenticates, then the named method runs and returns an ApiResponse.
5. OnResponse(apiResponse) gets a final pass at the op list.
6. The response body is { "data": [ {o,k,p1,p2}, … ] }.
7. $ApiRequestSuccess parses it and $WebAct applies each op in order.

Choosing between them

Hard navigation

If a response body begins with <!DOCTYPE html>, the client does not try to parse it as operations. It calls document.write(body) and replaces the page wholesale.

This is the escape hatch used for session-expiry redirects and login hand-offs, where the server decides mid-request that the user should be looking at a different document entirely.

Page Anatomy

A page is four co-located files sharing one base name. Nothing outside those four files is required to understand it, and nothing inside them is shared with another page.

The four files

The framework finds the last three by name. You write Contact.cs, request Contact, and the HTML, script and stylesheet are located and injected without registration.

Self-contained, duplicate-don't-abstract

This is the single most important convention in a SkyNet codebase, and the one that most surprises developers arriving from layered architectures.

A page owns its own CSS prefix, its own JS namespace, and its own C# methods and DTOs. Prefer copying a block into a second page over introducing a shared helper. The only cross-page C# sharing is a *Model.cs file holding plain DTO or enum declarations.

Naming and prefixes

Every CSS class and element id in a page carries a short page-unique prefix. Pick three to six characters derived from the page name and use it everywhere in that page.

/* prefix: cnt- */
.cnt-wrap    { display:flex; }
.cnt-field   { margin-bottom:14px; }
.cnt-input   { width:100%; }
.cnt-btn     { background:#D97757; }

The JS namespace rule

A page script is REQUIRED to be a single IIFE assigned to <PageName>Js, exposing a small surface through its return object. Nothing else is declared at global scope.

var ContactJs = (function () {

    // private
    function val(id) { var e = document.getElementById(id); return e ? e.value : ''; }

    function save() {
        $WaitOn();
        $ApiRequest('Save', JSON.stringify([
            { key: 'name', vlu: val('cnt-name') }
        ]));
    }

    function onSaved(msg) { /* called by the server via ExecuteScript */ }

    function reveal() { /* wire events, set initial state */ }

    return {
        reveal:  function ()    { reveal(); },
        save:    function ()    { save(); },
        onSaved: function (m)   { onSaved(m); }
    };

})();

document.addEventListener('DOMContentLoaded', function () { ContactJs.reveal(); });

The exposed surface is typically reveal plus the event handlers that markup calls by name and the callbacks the server invokes by name. Anything the server or the HTML refers to must be on the return object; anything else stays private.

Placeholders

The .html file is static markup containing tokens. The class replaces them in OnInitialized.

<div class="cnt-wrap">
  <h1 class="cnt-title">{plhd_title}</h1>
  <input class="cnt-input" id="cnt-name" value="{plhd_name}" />
  <div class="cnt-rows">{plhd_rows}</div>
</div>

public override async Task OnInitialized()
{
    HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText
        .Replace("{plhd_title}", HtmlEncode(title))
        .Replace("{plhd_name}",  HtmlEncode(name))
        .Replace("{plhd_rows}",  await BuildRows());
}

Conventions worth keeping:

• Prefix tokens {plhd_…} so they are greppable and never collide with CSS or translation syntax.
• Replace every token you declare. An unreplaced token renders literally on the page.
• HtmlEncode any value that came from the database or the user. The replacement is a raw string splice — nothing escapes it for you.

Models and DTOs

A page keeps its own DTOs in its own file. When two pages in the same area genuinely need the same shape, it goes in that area's single Models/<Area>Model.cs — declarations only, no behaviour.

If a type is used by one page, put it in that page's file. Promoting it to the area model is a deliberate decision, not a default.

WebPage Class

Every page derives from SkyNet.WebPage. It supplies the document, the lifecycle hooks, the translation surface, and — because it extends WebCore — the entire server utility API unqualified.

Declaring a page

using SkyNet;

namespace MyApp.codes
{
    public class Contact : WebPage
    {
        public override async Task OnInitialized()
        {
            HtmlDoc.SetTitle("Contact");
            HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText.Replace("{plhd_name}", HtmlEncode(name));
        }

        public async Task<ApiResponse> Save()
        {
            ApiResponse response = new ApiResponse();
            // ... work ...
            response.ExecuteScript("ContactJs.onSaved();");
            return response;
        }
    }
}

There is no attribute, no registration, no route entry. The framework resolves Contact from the executing assembly by class name.

Properties

Lifecycle hooks

Order

The app base-class pattern

Products built on SkyNet normally insert one application-wide base class between WebPage and every page, to hold concerns that genuinely are global: authentication, translation, run-mode checks.

public class WebBase : WebPage
{
    public override async Task<string> OnInit(string type, string method)
    {
        AuthData? auth = Helper.GetAuthData();
        if (auth == null)
            return "Your session has expired. Please sign in again.";

        return string.Empty;   // empty = proceed
    }
}

Pages then derive from WebBase instead of WebPage. Pre-authentication pages — sign-in, sign-up, password reset — derive from WebPage directly so the gate does not lock them out.

Partial pages

PartialDocument("Detail") runs another page's full GET lifecycle and hands you its HtmlDocument instead of writing it to the response. Pair it with SetElementContents to swap a region of the current page:

public async Task<ApiResponse> OpenArea()
{
    string t = GetDataValue("t");   // target element id
    string p = GetDataValue("p");   // page class name

    HtmlDocument htmlDoc = await PartialDocument(p);
    ApiResponse response = new ApiResponse();
    response.SetElementContents(t, htmlDoc);
    return response;
}

This is the mechanism behind shell-plus-content layouts, tab strips and drill-in overlays. It is covered in full in Areas & Partials.

Translation members

Translation = true covers the rendered document. It does not cover the op list a POST returns, because that is built after the render pipeline. To translate those, pass the response through TranslateApiResponse on the way out:

response.ExecuteScript("ContactJs.onError('{!Invalid email or password.!}');");
return TranslateApiResponse(response);

See Translation for the token syntax and the dictionary table.

Other members

HtmlDocument

HtmlDoc is the document under construction during a GET. You fill its body, add anything extra the head needs, and queue the operations that should run the moment the page lands.

Properties

Body text and placeholders

The framework loads htmls/<Page>.html into HtmlBodyText before OnInitialized runs. Your job is to replace the tokens:

HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText
    .Replace("{plhd_title}",  HtmlEncode(title))
    .Replace("{plhd_count}",  count.ToString())
    .Replace("{plhd_rows}",   rowsHtml);

Head and assets

public override async Task OnInitialized()
{
    HtmlDoc.SetTitle("MyApp — Contact");
    HtmlDoc.AddCSSFile("global.css");          // extra, shared
    HtmlDoc.AddJsFile("chart.min.js");          // extra, third party
    // Contact.js and Contact.css need no mention
}

InitialScripts

HtmlDoc.InitialScripts is an ApiResponse whose operations run when the document loads. It is how the server hands the page its starting state without embedding a script block in the markup.

HtmlDoc.InitialScripts.SetVariableData("ContactText", new
{
    btn_save   = "{!Save Changes!}",
    saving     = "{!Saving…!}",
    err_name   = "{!Please enter a name.!}"
}, HtmlTranslator);

HtmlDoc.InitialScripts.Navigate("Login");   // or bail out entirely

Every ApiResponse method is available on it — SetElementContents, StoreLocalValue, SetCookie, ExecuteScript, Navigate. It is the natural place to redirect an unauthenticated visitor during OnInitialized.

Content Security Policy

A CSP header is emitted by default. Inline script pushed through opcode 80 is nonce-wrapped so it passes, but third-party script from another origin does not.

Switch it off for the single page that needs it, never application-wide.

Building without a template

A page is not obliged to have an .html file. You can compose the body entirely in C# — with string building, or with ToolKit:

HtmlTag h = new HtmlTag(HtmlTags.h3);
h.InnerText = "Hello";
HtmlDoc.HtmlBodyText = h.HtmlText;

The template approach is preferred for anything a person will design or restyle; server-side building earns its place for markup that is genuinely data-shaped, such as a grid whose columns come from configuration.

ApiResponse

The command container. Every server method invoked from the client returns one. You populate it with builder calls; the framework serializes them into the op list the browser applies.

The model

ApiResponse is not a data envelope — it carries no payload for the client to interpret. It carries instructions, executed in the order you added them.

public async Task<ApiResponse> ProcessForm()
{
    ApiResponse response = new ApiResponse();          // 1. instantiate

    response.SetElementContents("statusMessage", "Processing complete.");
    response.SetElementStyle("submitButton", "display", "none");   // 2. populate
    response.Navigate("ConfirmationPage");

    return response;                                     // 3. return
}

Three ways to target an element

Most methods come in three forms. Learn the suffix and the whole API collapses to a third of its size.

Contents and values

Attributes

Styles

Structure

Scripts, links and client calls

ExecuteScript is the workhorse: it is how a server method hands control back to page JS after the DOM work is done.

response.SetElementContents("cnt-rows", rowsHtml);
response.ExecuteScript("ContactJs.onRowsLoaded();");

Variable data

Ships a typed or anonymous object to the client, retrieved there with $GetVarData(name). Pass HtmlTranslator as the third argument to run {!…!} tokens in the values through the dictionary first. Covered in CS → JS Transfer.

Storage and cookies

Popups and modals

Navigation and files

Ordering and composition

Operations apply in the order you add them. That has practical consequences:

• Populate an element before the ExecuteScript that reads it.
• Navigate ends the page — anything queued after it is pointless.
• SetCookie before Navigate, or the cookie is written into a document that is already being torn down.

response.SetCookie(Helper.AuthCookieName(), authEncoded, 1728000);
response.Navigate("Home");
return response;

Data Access

You write SQL. SQLData parameterizes it, executes it, and hands back a DataTable or a typed list alongside an error string. There is no ORM, no change tracker, no lazy loading.

SQLData

The parameterless constructor builds its own SQLInfo from configuration, so the usual call is simply:

SQLData msql = new SQLData();
var (dt, emsg) = await msql.GetDataAsync(sql, parameters);

The (data, emsg) idiom

Reads return a tuple: the data, and an error string that is empty on success. Nothing throws for an ordinary SQL failure. Check the string.

var (dt, emsg) = await Helper.GetDataTable(sql, parms);
if (!string.IsNullOrEmpty(emsg))
{
    response.ModalWindow("Issue Found", Helper.ErrContentHtml(emsg));
    return response;
}
if (dt == null || dt.Rows.Count == 0)
{
    // no rows is not an error — decide what it means here
}

Writes return only the error string — empty means it worked:

string putErr = await new Helper(this).PutData(sqls, parms);
if (!string.IsNullOrEmpty(putErr)) { /* handle */ }

Parameterization

REQUIRED Every value that reaches SQL goes through a SqlParameter. Concatenating user input into a query string is the one thing this framework gives you no protection against.

var parameters = new List<SqlParameter>
{
    new SqlParameter("userid", SqlDbType.NVarChar) { Size = 50,  Value = userId },
    new SqlParameter("email",  SqlDbType.NVarChar) { Size = 200, Value = email  },
    new SqlParameter("amount", SqlDbType.Decimal)                { Value = amount }
};

string sql = @"SELECT ACCT_ID, ACCT_NAME
                 FROM ACCT
                WHERE USER_ID = @userid AND ACCT_NAME LIKE @email";

Note the parameter name is given without the @ in the constructor and with it in the SQL. Always set Size on string parameters — omitting it lets ADO.NET infer a size from the current value, which defeats plan reuse.

Batch writes

PutDataAsync takes a list of statements sharing one parameter list, executed together. This is how multi-table operations stay consistent.

var sqls = new List<string>
{
    @"INSERT INTO ACCT (ACCT_ID, USER_ID, ACCT_NAME, SYSDTE)
      VALUES (@acctid, @userid, @acctname, GETDATE())",

    @"INSERT INTO ACCTLOG (LOG_ID, ACCT_ID, LOG_MEMO, SYSDTE)
      VALUES (UPPER(CONVERT(NVARCHAR(50), NEWID())), @acctid, N'Opening', GETDATE())"
};

var parms = new List<SqlParameter>
{
    new SqlParameter("acctid",   SqlDbType.NVarChar) { Size = 50,  Value = acctId },
    new SqlParameter("userid",   SqlDbType.NVarChar) { Size = 50,  Value = userId },
    new SqlParameter("acctname", SqlDbType.NVarChar) { Size = 100, Value = name   }
};

string err = await new Helper(this).PutData(sqls, parms);

Typed lists

DataTableListT<T> maps a DataTable onto plain classes by matching column names to property names.

public class AcctRow
{
    public string ACCT_ID   { get; set; } = string.Empty;
    public string ACCT_NAME { get; set; } = string.Empty;
    public decimal ACCT_DRCR { get; set; } = 0;
}

var (rows, emsg) = await Helper.GetListT<AcctRow>(sql, parms);

Property names must match the SELECT list exactly. A typo produces a default value, not an error — which is why reading DataRow directly is just as common in SkyNet codebases for one-off reads.

The Helper pattern

Products wrap SQLData in an application Helper class that adds cross-cutting behaviour to every call. This is the layer where audit logging and read-only mode live.

public static async Task<(DataTable dt, string emsg)> GetDataTable(
    string sSql, List<SqlParameter>? parameters = null)
{
    SQLData msql = new SQLData();
    return await msql.GetDataAsync(sSql, parameters);
}

public async Task<string> PutData(List<string> sSql, List<SqlParameter>? parameters = null)
{
    if (await AppRunMode() == 2)
        return "The requested process is currently locked in archive mode.";

    sSql.AddRange(SqlLogSql(sSql, parameters));   // append audit INSERTs

    SQLData msql = new SQLData();
    return await msql.PutDataAsync(sSql, parameters);
}

Two behaviours worth copying:

• Archive mode blocks writes. When the application's run mode is 2, PutData refuses before touching the database. See Run mode.
• Every write is audited. The helper appends an INSERT into an audit table capturing the calling area, class and method (via [CallerMemberName]), the user, the IP, the SQL and the parameters — in the same batch, so the audit row cannot be lost if the write succeeds.

SQLInfo

Connection settings, read from application.cfg by default.

The connection string template pins TrustServerCertificate=True and a 4096-byte packet size. The parameterless constructor reads app.sqldb.source, catalog, id, password and timeout; the explicit constructor lets a page reach a second database.

WebCore

The server utility surface. WebPage extends it, so inside a page class every member below is callable unqualified. Instantiate new WebCore() only from static helpers that have no page instance.

Application identity

Folders and paths

Three families: …Folder (the configured folder name), …Path (the physical path), …AliasPath (the URL alias).

Also PhysicalFolder, ConfigFolder, CoreFile, WaitImageUri.

Client context

Reading request values

Cryptography

Serialization and mapping

Links, actions and downloads

Text, validation and formatting

Export

Write into TempPath, then hand the browser a link with DownLoadFileLink and response.DownloadFile(...).

Reflection and enums

The framework resolves pages by name, and exposes the same machinery for application use — dynamic option lists, configuration-driven screens, admin tooling.

Files and partials

PartialDocument is documented in Areas & Partials.

Support Classes

Everything else in the SkyNet namespace: mail, files, images, JSON, XML, encryption, expression evaluation and streaming downloads.

Encrypt

Symmetric, two-way. The page's Encryptor property is a ready-made instance keyed from app.Settings.encryptkey, so you rarely construct one.

// write
string json = SerializeObject(authData, typeof(AuthData));
response.SetCookie(cookieName, Encryptor?.EncryptData(json) ?? string.Empty, 1728000);

// read
string cookie = CookieValue(cookieName) ?? string.Empty;
string back   = Encryptor?.DecryptData(cookie) ?? string.Empty;
AuthData? auth = (AuthData?)DeserializeObject(back, typeof(AuthData));

Mail

MailInfo's parameterless constructor reads app.mail.server, port, addr, id, password, title and credentials from configuration, so the common case needs no setup:

try
{
    var mail = new SkyNet.Mail
    {
        ToAddr  = new[] { email },
        Subject = "Verification Code",
        Body    = string.Format(SkyNet.Mail.TempMailBody, $@"
            <div style='font-family:system-ui,sans-serif;max-width:480px;'>
                <h2>Verify your email</h2>
                <div style='font-size:32px;font-weight:700;letter-spacing:8px;'>{code}</div>
                <p>This code expires in <strong>15 minutes</strong>.</p>
            </div>")
    };
    mail.SendMail();
}
catch { /* the code is already saved — do not fail the request on mail trouble */ }

FileHandler

ImageHandler

JsonHandler

DataTableToJsonTree turns a self-referencing table (id / parent-id) into nested JSON — the shape a tree view or nested menu wants, built in one call from one flat query.

XmlTool

MathEval

Evaluates arithmetic and conditional expressions supplied as text — for formula columns and configurable rules.

== is accepted; >, <, <> and != are not — use the three-letter forms.

FileDownload

Serves a file from an encrypted parameter produced by FileSteamParam / DownLoadFileLink. The parameter carries the name, the path and a timestamp; links expire one minute after issue, and an expired or path-less request throws Forbidden.

DynamicModel

A DynamicObject whose members are a dictionary — for rows whose shape is not known until runtime. Prefer a declared DTO whenever the shape is known: a typed class is checked by the compiler and is far easier for an assistant to work against.

HtmlHandler and HtmlTag

Server-side HTML construction, covered with ToolKit in the next section.

ToolKit — Server-Side HTML

A typed object model for composing markup in C# before the GET response goes out. It is an alternative to the .html template, not a replacement for it — and knowing which to reach for matters.

Three ways to produce a body

HtmlTag

The primitive. One element, its attributes, its styles and its inner text.

public class MyPage : WebPage
{
    public override async Task OnInitialized()
    {
        HtmlTag hello = new HtmlTag(HtmlTags.h3);
        hello.InnerText = "Hello World";

        HtmlDoc.HtmlBodyText = hello.HtmlText;
    }
}

Tag and style names come from the HtmlTags, HtmlAttributes and HtmlStyles constant sets, so they are compile-checked rather than spelled out as strings.

Deriving a control

Because HtmlTag is designed for inheritance, a reusable element is a small class that configures itself in its constructor.

[Serializable]
public class LinePitch : HtmlTag
{
    public override string HtmlText => Html();

    public LinePitch(int lineHeight = 0)
    {
        SetStyle(HtmlStyles.display, "block");
        SetStyle(HtmlStyles.height, lineHeight + "px");
    }
}

[Serializable]
public class Label
{
    public string  IDTag { get; set; } = string.Empty;
    public HtmlTag Wrap  { get; set; } = new HtmlTag();

    public string HtmlText => Wrap.Html();

    public Label(string labelText)
    {
        Wrap.SetAttribute(HtmlAttributes.data_controlname, "Label.Wrap");
        Wrap.SetStyle(HtmlStyles.overflow, "hidden");
        Wrap.InnerText = labelText;
    }
}

HtmlHandler

Collects elements and renders them together. With includeElementId set, every element is emitted with an id — which is what makes the result addressable afterwards by ApiResponse.

Control classes

ToolKit ships composed controls built on the same primitive.

Layout and containers

Wrap · Stacker (+Column) · Grid (+Row, Column, TR, TH, TD) · ItemPanel · ContentsBox · HtmlContentsBox · HtmlElementBox · HtmlWrapper · LinePitch · Parallax (+Section)

Data display

DataGrid (+Container, TableColumn, TableRow, TR, TH, TD) · DataList · ItemList (+Item) · TreeView / TreeView2 (+TreeItem) · Paging · Progress (+Item) · Timer

Input

Texts · TextArea · Dropdown · CheckBox · Radio · Hidden · FileUpload · Button · Buttons · ImageButton

Navigation and chrome

MenuList · MenuIcon · MenuPanel (+Column, Column.Item) · TabStrip · DialogBox · Label · ImageBox · iFrame

Enums

Mixing approaches

The three are not exclusive, and the usual arrangement uses all of them: a template for the page shell, string composition for repeating rows, and ToolKit where structure is genuinely dynamic.

// template holds the shell; this fills one region
StringBuilder sb = new StringBuilder();
foreach (DataRow row in dt.Rows)
{
    sb.Append("<div class=\"cnt-row\">");
    sb.Append("<span class=\"cnt-name\">" + HtmlEncode(row["NAME"]?.ToString()) + "</span>");
    sb.Append("</div>");
}

HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText.Replace("{plhd_rows}", sb.ToString());

Keep generated markup addressable

Whatever you build server-side, the ApiResponse layer can only change what it can find. Give generated elements stable ids, names or data-elmid attributes at build time so a later round trip can target them.

skynet.core.js

The client engine. One file, no modules, no dependencies. It is injected automatically on every GET, exposes everything as $-prefixed globals, and applies the operations the server sends.

How it loads

The framework injects skynet.core.js (minified as skynet.core.min.js) into every rendered document. You never reference it, never import it, and never version it against your pages. By the time your page script runs, every $ global is defined.

What it injects into the page

On DOMContentLoaded the engine builds three things and attaches two global listeners. These exist on every page whether you use them or not.

Engine-owned globals

$ClickListener and $ResizeListener are the sanctioned extension points. Push a function onto either array and the engine will call it:

$ResizeListener.push(function () { ContactJs.relayout(); });

Naming discipline

Two mechanisms in the engine read function names at runtime:

These let a handler call its server-side namesake without repeating it:

function saveProfile() {
    $ApiRequest();                      // → calls Contact.saveProfile() on the server
}

Three constraints follow, and all three are easy to violate by accident:

The shape of the API

Every global begins with $. There are no namespaces, no imports and no load order to manage — if the engine is present, the whole surface is present.

The full list is in the $ global reference.

Error handling

The default error callback shows an alert, first checking whether the message is a localStorage key it should translate. Pass your own fourth argument to $ApiRequest to replace it.

Do not modify the engine

skynet.core.js is framework-supplied and shared by every application on the framework. Page behaviour belongs in the page's own IIFE; cross-page behaviour belongs in your own script file added with HtmlDoc.AddJsFile. Editing the engine forks it from every other product on SkyNet and makes upgrades a merge.

$ApiRequest

The one call that crosses the wire. Everything a page does after it loads goes through here or through one of its two shorthands.

The call forms

function saveProfile() {
    var data = [ { key: 'name', vlu: userName } ];

    // same page, same method name as the calling function — name inferred
    $ApiRequest();

    // same page, same method name, with a payload
    $ApiRequest('saveProfile', JSON.stringify(data));
    $ApiRequest(null, JSON.stringify(data));          // equivalent

    // same page, a different method
    $ApiRequest('myProfile', JSON.stringify(data));

    // another page's method
    $ApiRequest('anotherPage/saveProfile');
    $ApiRequest('anotherPage/myProfile', JSON.stringify(data));

    // with explicit callbacks
    $ApiRequest('anotherPage/saveProfile', JSON.stringify(data), onSaveSuccess, onSaveError);
}

The two shorthands

$Call resolves two special tokens on the right-hand side before sending — useful for wiring straight from markup with no page JS at all:

<button onclick="$Call('Search','keyword=::&status=:::&page=1')">Search</button>

That sends keyword = the value of #keyword, status = the checked values named status, and page = the literal 1. $Call also raises the wait overlay for you; $ and $ApiRequest do not.

URI resolution

The target is turned into a URL relative to the current path, not to the site root:

$appPath() keeps the first two path segments of the current location. The practical consequence is that 'Save' targets the current page and 'OtherPage/Save' targets a sibling — the folder a class lives in never appears, because routing is by class name.

The POST envelope

Every call sends far more than its payload. $ApiRequest builds FormData and appends:

How form values are collected

• Keyed by id || name — id wins for most inputs, name wins for checkboxes and radios.
• Checkboxes and radios are sent only when checked, carrying their value, or "1" when the value is empty or "on".
• file inputs append their File objects, so uploads need no special handling.
• select, textarea and button send their value.

Response handling

• A body starting with <!DOCTYPE html> replaces the document — the hard-navigation path.
• Otherwise the wait overlay drops and the ops are applied.
• An empty body is a silent no-op, which is what a method returning an empty ApiResponse produces.
• A body that is neither is written into document.body along with the parse error.

The wait overlay

$WaitOff() is called for you on every response. $WaitOn() is not called for you except by $Call — so raise it yourself before a request that will take a moment:

$WaitOn();
$ApiRequest('Save', JSON.stringify(data));

Keyboard helpers

<input id="cnt-search" onkeydown="$KeyEvent(event, 13, 'Search')" />

These read the caller's arguments at runtime and carry the same naming constraints as the inferred call forms.

WebAct Opcodes

The wire format between ApiResponse and the DOM. You will not write these by hand, but reading them is the fastest way to debug a call that appears to do nothing.

The shape of an op

$WebAct loops the array and switches on o, applying each in order. An unknown opcode is silently ignored.

Target forms

Most DOM operations exist in three numbered variants. The arithmetic is worth memorising: the name-form is the id-form plus 30, and the data-elmid forms live in the 110–126 band.

The full table

Document and elements

Scripts, links and call-backs

Storage and cookies

Overlays and navigation

Undefined handlers

Reading ops while debugging

When a server call "does nothing", the op list tells you which of three things happened. Open the network tab and look at the response body.

$ Global Reference

Every function skynet.core.js exposes, grouped by what it does. Entries marked PAGE are the ones page code normally calls; the rest are engine internals, documented because they turn up in stack traces.

Calls and transport

Elements

Reading values

Navigation

Overlays, popups and modals

Layout and scrolling

Tables

Inserted detail rows carry an id beginning _$trc$_; that marker is how the toggle helpers recognise and remove their own rows.

Scripts and stylesheets

Variable data

Utility

Client Storage

Three stores, three scoping rules, and one behaviour that surprises everyone: page-scoped localStorage is transmitted to the server on every request.

localStorage namespacing

SkyNet namespaces localStorage keys by page so two pages can use the same short key without colliding.

The page prefix is derived from the current URL — the last path segment, minus any extension. A key containing #global. anywhere is left untouched.

From the server

From the client

Storage is transmitted on every request

This is the part that catches people. $getLocalData runs on every $ApiRequest and appends storage to the outgoing FormData:

So a value stored under filter arrives server-side as GetDataValue("filter"), with the page prefix stripped. Global keys arrive under their full #global. name.

sessionStorage

Because sessionStorage is neither namespaced nor transmitted, prefix its keys yourself and read them explicitly when you need them server-side.

Cookies

Choosing a store

CS → JS Data Transfer

The supported way to hand structured data to a page's JavaScript. One call on the server, one call on the client, no inline JSON blob in the markup.

The two calls

HtmlDoc.InitialScripts.SetVariableData("ContactText", new
{
    btn_save    = "Save Changes",
    saving      = "Saving…",
    err_name    = "Please enter a name.",
    err_generic = "Something went wrong. Please try again."
});

var data = $GetVarData('ContactText');
var label = data.btn_save;

An anonymous object is the usual argument; a declared class works identically. The property names become the JavaScript keys verbatim.

The wire format

The object is serialized to JSON, UTF-8 encoded, base64'd, and delivered as a call to $SetVarData. The client decodes it into a single global store:

Two things follow from this that matter in practice.

When it arrives

Values queued in HtmlDoc.InitialScripts execute after the page's script file has been evaluated. At the moment Contact.js is parsed and its DOMContentLoaded handler runs, $VarData is still empty.

The lazy-read pattern

Read at first use, and cache only once the data is actually there:

var TXT = null;
function t(k) {
    if (!TXT) { TXT = $GetVarData('ContactText'); }
    return (TXT && TXT[k]) ? TXT[k] : '';
}

If the first call happens too early, TXT stays falsy and the next call retries. No timing assumption, no polling, no ordering requirement.

Delete-on-read

The default is to remove. Two reads of the same name return the value and then undefined. Either cache the first result — as the lazy pattern does — or pass false explicitly.

Translated payloads

Pass the page's HtmlTranslator as the third argument and {!…!} tokens in the values are resolved before encoding:

HtmlDoc.InitialScripts.SetVariableData("ContactText", new
{
    btn_save = "{!Save Changes!}",
    saving   = "{!Saving…!}",
    err_name = "{!Please enter a name.!}"
}, HtmlTranslator);

This is REQUIRED for any user-visible text the client writes into the DOM. Without the third argument the tokens travel to the browser literally and the user sees {!Save Changes!} on a button.

What to put through it

Legacy inline JSON

Sending data mid-session

SetVariableData is not restricted to InitialScripts. Any ApiResponse can carry it, which is how a server method hands the page a fresh object without rendering markup:

public async Task<ApiResponse> LoadOptions()
{
    ApiResponse response = new ApiResponse();
    response.SetVariableData("ContactOptions", options);
    response.ExecuteScript("ContactJs.onOptions();");
    return response;
}

Queue the data before the script that reads it — ops apply in order.

Translation

Mark text with {!…!}, store the wording in a database table, and the framework substitutes it on the way out. Copy becomes data — editable without a deploy, in any number of languages.

The token

Wrap any visible string in the markup:

<h1 class="cnt-title">{!Welcome back!}</h1>
<label class="cnt-label">{!Email!}</label>
<input placeholder="{!you@example.com!}" />
<button>{!Sign In!}</button>

The key is the English text itself. There is no separate identifier to invent, keep in sync, or look up. A missing dictionary row leaves the literal text on screen — so an untranslated page degrades to readable English rather than to label.login.title.

Enabling it on a page

public Contact()
{
    Translation = true;

    string pageName = this.GetType().ToString().Split('.').LastOrDefault() ?? this.GetType().Name;
    var pageDict = Helper.GetPageDict(pageName).GetAwaiter().GetResult();
    if (pageDict != null && pageDict.Count > 0) HtmlTranslator.Add(pageDict);
}

• Translation = true activates the translator, driven by the browser's language.
• HtmlTranslator.Add(…) loads this page's dictionary rows, which take priority over anything the translator would otherwise produce.

Both belong in the constructor, because the dictionary must be present before any rendering or response building happens.

When substitution happens

Translation runs on the finished HTML document, immediately before it is sent — in OnAfterRender, after every placeholder replacement and every fragment you built.

Three useful consequences:

• Tokens survive everything upstream — you can place them inside attributes, inside strings you concatenate in C#, inside fragments built row by row.
• Placement next to a {plhd_*} placeholder is safe: {plhd_appname} {!is currently unavailable.!}
• It is server-side and has nothing to do with client JavaScript.

The dictionary table

CREATE TABLE [dbo].[XYSDICT](
    [TARGET]     [nvarchar](50)  NOT NULL,   -- page name, or '*' for every page
    [ISOCODE]    [nvarchar](10)  NOT NULL,   -- 'en-US', 'ko-KR', or '*'
    [KEYWORD]    [nvarchar](100) NOT NULL,   -- the text inside {! !}
    [TRANSLATED] [nvarchar](max) NOT NULL,   -- what the user sees
 CONSTRAINT [PK_XysDict] PRIMARY KEY CLUSTERED ([TARGET], [ISOCODE], [KEYWORD])
)

Wildcards

• TARGET = '*' — applies to every page. Use for genuinely universal words: Save, Cancel, Delete.
• ISOCODE = '*' — applies to every locale.
• A page-specific row wins over a '*' row.

The lookup

The standard loader resolves the locale with a fallback chain and returns rows for the page plus the wildcards:

public static async Task<List<Translator.DictionaryEntry>> GetPageDict(
    string pagename, string clientLanguage = "")
{
    string lang = clientLanguage;
    if (string.IsNullOrEmpty(lang)) lang = new WebCore().ClientLanguage ?? string.Empty;
    if (string.IsNullOrEmpty(lang)) lang = "en-US";

    string sSql = @"IF EXISTS (SELECT * FROM XYSDICT WHERE ISOCODE = @isocode)
       BEGIN
           SELECT TARGET, ISOCODE, KEYWORD, TRANSLATED FROM XYSDICT
            WHERE (TARGET = @pageid OR TARGET = N'*')
              AND (ISOCODE = N'*' OR ISOCODE = @isocode)
            ORDER BY KEYWORD
       END
       ELSE
       BEGIN
           SELECT TARGET, ISOCODE, KEYWORD, TRANSLATED FROM XYSDICT
            WHERE (TARGET = @pageid OR TARGET = N'*')
              AND (ISOCODE = N'*' OR ISOCODE = N'en-US')
            ORDER BY KEYWORD
       END";

    // ... parameters, execute, map rows to Translator.DictionaryEntry ...
}

If the requested locale has no rows at all, the query falls back to en-US — so adding a language is purely additive and a partially translated language degrades per-string rather than failing wholesale.

The Translator class

Add(key, word) lets a page inject a translation at runtime without a table row — useful for text assembled from data.

Translating ApiResponse content

Translation = true covers the rendered document only. An op list built during a POST is produced after that pipeline, so its text is not translated by default.

public async Task<ApiResponse> SignIn()
{
    ApiResponse response = new ApiResponse();

    if (bad)
    {
        response.ExecuteScript("ContactJs.onError('{!Invalid email or password.!}');");
        return TranslateApiResponse(response);      // ← resolves the token
    }

    response.Navigate("Home");
    return TranslateApiResponse(response);
}

Applying it uniformly to every return is simpler than deciding case by case, and costs nothing on responses that contain no tokens.

What gets translated, and what does not

Working practice

1. Write the page in plain English.
2. Wrap every visible string in {!…!} — text nodes and placeholder attributes.
3. Move any user-visible JS literal into a SetVariableData payload, tokens and all.
4. Extract the distinct tokens and generate idempotent INSERTs for ISOCODE = 'en-US' with TRANSLATED = KEYWORD.
5. Add other locales as rows whenever you are ready. No code changes.

Areas & Partial Pages

Areas organise code on disk. Partial pages let one page render another into a region of itself — the mechanism behind shells, tabs and drill-in panels.

Folder layout

Areas are a filing convention. They do not appear in URLs, in call targets or in class resolution.

Class-name routing

SkyNet resolves a page by looking up the class name in the executing assembly. The namespace and folder are irrelevant to the caller:

PartialDocument

PartialDocument runs another page's full GET lifecycle — constructor, OnInit, OnInitialized, translation — and returns its HtmlDocument instead of writing it to the response. Hand that to SetElementContents and the region is replaced.

public async Task<ApiResponse> OpenArea()
{
    string t = GetDataValue("t");   // target element id
    string p = GetDataValue("p");   // page class name

    HtmlDocument htmlDoc = await PartialDocument(p);
    ApiResponse response = new ApiResponse();
    response.SetElementContents(t, htmlDoc);
    return response;
}

function go(page) {
    $WaitOn();
    $ApiRequest('Home/OpenArea', JSON.stringify([
        { key: 't', vlu: 'main-content' },
        { key: 'p', vlu: page }
    ]));
}

One method serves every menu item. The partial's own .js and .css are appended to the document as part of the injection.

The shell pattern

The usual arrangement: one page owns the chrome, every other page is content injected into it.

<div class="hm-shell">
  <aside class="hm-side">
    <button data-page="Sales_Order">{!Orders!}</button>
    <button data-page="Sales_Invoice">{!Invoices!}</button>
  </aside>
  <main class="hm-main" id="main-content"></main>
</div>

If linkability matters, use Navigate per page instead and let each page render its own chrome — at the cost of duplicating the shell markup into every page. Both are legitimate; choose once, per application.

Script timing

Two ways out. Either have the partial start itself:

var DetailJs = (function () { /* … */ })();

DetailJs.reveal();   // runs when the injected script is evaluated

Or have the injector wait for the namespace, which is the more robust option because script injection is asynchronous:

response.SetElementContents("main-content", htmlDoc);
response.ExecuteScript(
    "(function w(){ if(window.DetailJs){ DetailJs.reveal(); } else { setTimeout(w,30); } })();");

Carrying state across an injection

Re-injecting a partial rebuilds it from scratch: which tab was open, which row was selected and any success message are all gone. Put the intent somewhere that survives, then restore on the way in.

function reload(pane) {
    try { sessionStorage.setItem('detail_pane', pane || 'main'); } catch (e) { }
    $WaitOn();
    $ApiRequest('Home/OpenArea', JSON.stringify([
        { key: 't', vlu: 'main-content' },
        { key: 'p', vlu: 'Detail' }
    ]));
}

function reveal() {
    var pane = 'main';
    try {
        pane = sessionStorage.getItem('detail_pane') || 'main';
        sessionStorage.removeItem('detail_pane');
    } catch (e) { }
    showPane(pane);
}

Reloading the partial after a write is often better than patching the DOM: the rows come back rendered, encoded and translated by the same server code that built them the first time, with no second code path to keep in step.

Authentication in partials

Configuration & Hosting

One pipe-delimited file holds every application setting. Run mode is the exception — it lives in the database so it can be changed without a restart.

application.cfg

A plain text file in the app-config folder, one key | value per line, split into a system section and a custom section.

****************************************************
***** 1. System Configuration: values may change, do not delete
***** 2. app.app.runmode : 0.Demo, 1.Production
****************************************************
app.app.name             | My App 1.0
app.app.version          | 1.0
app.app.releasedate      | 5/1/2026
app.app.runmode          | 0
app.app.startup          | login
app.app.regno            | 8ad307ce-efee-4633-a061-a35a94efbd6b
app.Settings.encryptkey  | %My%Key!%
app.Settings.isocode     | en-US
app.Settings.pagetimeout | 12000
app.folders.code         | codes
app.folders.html         | htmls
app.folders.script       | scripts
app.folders.style        | styles
app.folders.image        | images
app.folders.temp         | temp
app.folders.data         | data
app.folders.log          | logs
app.folders.bin          | bin
app.mail.server          | smtp.office365.com
app.mail.port            | 587
app.mail.addr            | noreply@example.com
app.mail.id              | noreply@example.com
app.mail.password        | ********
app.mail.title           | Notification_Center
app.mail.credentials     | 0
app.sqldb.source         | (local)
app.sqldb.catalog        | MyAppDb
app.sqldb.id             | sa
app.sqldb.password       | ********
app.sqldb.timeout        | 3600
****************************************************
***** Custom Configuration
***** Calling Example: GetWebEnv("user.sso.uri")
****************************************************
user.sso.uri             | http://localhost/skysso/WebApi.api
user.sso.key             | F412D47079634EA494E29055F27F1BF9
user.folders.photo       | photos

Reading values

System keys are also surfaced as typed properties — WebAppName, EncryptKey, ScriptPath, PageTimeout and the rest. GetWebEnv is how you reach your own custom keys.

Run mode

Products store it as an options row and expose it through a scalar function, so it can be flipped with an UPDATE — no deploy, no restart:

CREATE FUNCTION [dbo].[FN_ORIGINE_MODE]() RETURNS int AS
BEGIN
    DECLARE @SD02 nvarchar(100) =
        ISNULL((SELECT SD02 FROM XYSOPTION
                 WHERE STYPE = N'ORIGINE' AND SD01 = N'RunMode'), '0');
    RETURN(CONVERT(int, @SD02));
END

public async Task<string> PutData(List<string> sSql, List<SqlParameter>? parameters = null)
{
    if (await AppRunMode() == 2)
        return "The requested process is currently locked in archive mode.";
    // ... proceed ...
}

Hosting

SkyNet is ordinary ASP.NET Core on .NET 10. It runs on Windows and Windows Server, behind IIS or self-hosted on Kestrel.

What is distinctive is where static assets live. SkyNet serves them from the content-root folders named in application.cfg — scripts/, styles/, images/ — rather than from wwwroot.

What every host must do

Example: IIS

Under IIS the rules above are expressed in web.config:

<security>
  <requestFiltering>
    <hiddenSegments>
      <add segment="appConfig" />
      <add segment="codes" />
      <add segment="htmls" />
      <add segment="data" />
      <add segment="logs" />
    </hiddenSegments>
    <fileExtensions allowUnlisted="true">
      <add fileExtension=".cfg"    allowed="false" />
      <add fileExtension=".json"   allowed="false" />
      <add fileExtension=".dll"    allowed="false" />
      <add fileExtension=".exe"    allowed="false" />
      <add fileExtension=".pdb"    allowed="false" />
    </fileExtensions>
    <requestLimits maxAllowedContentLength="20971520" />
  </requestFiltering>
</security>

Uploads

Two independent limits apply and the framework one usually trips first, so raise both:

Deployment checklist

Worked Example

One complete page — list, form, save, delete — in all four files, with every round trip annotated. Read this once and the rest of the guide becomes reference material.

The page is Contact: it lists contacts belonging to the signed-in user, adds and edits one at a time, and deletes with confirmation. Prefix cnt-, namespace ContactJs.

Contact.cs

using Microsoft.Data.SqlClient;
using MyApp.codes.Shared;
using SkyNet;
using System.Data;
using System.Linq;
using System.Text;

namespace MyApp.codes.Areas.Crm
{
    public class Contact : WebBase
    {
        public Contact()
        {
            Translation = true;
            string pageName = this.GetType().ToString().Split('.').LastOrDefault() ?? this.GetType().Name;
            var pageDict = Helper.GetPageDict(pageName).GetAwaiter().GetResult();
            if (pageDict != null && pageDict.Count > 0) HtmlTranslator.Add(pageDict);
        }

        public override async Task OnInitialized()
        {
            AuthData? auth = Helper.GetAuthData();
            if (auth == null || string.IsNullOrEmpty(auth.USER_ID))
            {
                HtmlDoc.InitialScripts.Navigate("Login");
                return;
            }

            HtmlDoc.SetTitle("Contacts");

            HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText
                .Replace("{plhd_rows}", await BuildRows(auth.USER_ID));

            HtmlDoc.InitialScripts.SetVariableData("ContactText", new
            {
                btn_save    = "{!Save!}",
                saving      = "{!Saving…!}",
                err_name    = "{!Please enter a name.!}",
                err_email   = "{!Please enter a valid email address.!}",
                err_generic = "{!Something went wrong. Please try again.!}",
                ok_saved    = "{!Contact saved.!}",
                ok_deleted  = "{!Contact removed.!}",
                ask_delete  = "{!Remove this contact?!}"
            }, HtmlTranslator);
        }

        // ── round trip 1 ────────────────────────────────────────────
        public async Task<ApiResponse> Save()
        {
            ApiResponse response = new ApiResponse();

            AuthData? auth = Helper.GetAuthData();
            if (auth == null || string.IsNullOrEmpty(auth.USER_ID))
            {
                response.Navigate("Login");
                return TranslateApiResponse(response);
            }

            string contactId = GetDataValue("contactid").Trim();
            string name      = GetDataValue("cnt-name").Trim();     // straight off the form
            string email     = GetDataValue("cnt-email").Trim();

            if (string.IsNullOrEmpty(name))
            {
                response.ExecuteScript("ContactJs.onError('err_name');");
                return TranslateApiResponse(response);
            }

            var sqls  = new List<string>();
            var parms = new List<SqlParameter>
            {
                new SqlParameter("userid", SqlDbType.NVarChar) { Size = 50,  Value = auth.USER_ID },
                new SqlParameter("name",   SqlDbType.NVarChar) { Size = 100, Value = name         },
                new SqlParameter("email",  SqlDbType.NVarChar) { Size = 200, Value = email        }
            };

            if (string.IsNullOrEmpty(contactId))
            {
                contactId = Guid.NewGuid().ToString().ToUpper();
                sqls.Add(@"INSERT INTO CONTACT (CONTACT_ID, USER_ID, NAME, EMAIL, SYSDTE)
                           VALUES (@contactid, @userid, @name, @email, GETDATE())");
            }
            else
            {
                sqls.Add(@"UPDATE CONTACT SET NAME = @name, EMAIL = @email
                           WHERE CONTACT_ID = @contactid AND USER_ID = @userid");
            }
            parms.Add(new SqlParameter("contactid", SqlDbType.NVarChar) { Size = 50, Value = contactId });

            string putErr = await new Helper(this).PutData(sqls, parms);
            if (!string.IsNullOrEmpty(putErr))
            {
                response.ExecuteScript("ContactJs.onError('err_generic');");
                return TranslateApiResponse(response);
            }

            response.SetElementContents("cnt-rows", await BuildRows(auth.USER_ID));
            response.ExecuteScript("ContactJs.onSaved();");
            return TranslateApiResponse(response);
        }

        // ── round trip 2 ────────────────────────────────────────────
        public async Task<ApiResponse> Delete()
        {
            ApiResponse response = new ApiResponse();

            AuthData? auth = Helper.GetAuthData();
            if (auth == null || string.IsNullOrEmpty(auth.USER_ID))
            {
                response.Navigate("Login");
                return TranslateApiResponse(response);
            }

            var sqls = new List<string>
            {
                "DELETE FROM CONTACT WHERE CONTACT_ID = @contactid AND USER_ID = @userid"
            };
            var parms = new List<SqlParameter>
            {
                new SqlParameter("contactid", SqlDbType.NVarChar) { Size = 50, Value = GetDataValue("contactid").Trim() },
                new SqlParameter("userid",    SqlDbType.NVarChar) { Size = 50, Value = auth.USER_ID }
            };

            string putErr = await new Helper(this).PutData(sqls, parms);
            if (!string.IsNullOrEmpty(putErr))
            {
                response.ExecuteScript("ContactJs.onError('err_generic');");
                return TranslateApiResponse(response);
            }

            response.SetElementContents("cnt-rows", await BuildRows(auth.USER_ID));
            response.ExecuteScript("ContactJs.onDeleted();");
            return TranslateApiResponse(response);
        }

        // ── page-local fragment builder ─────────────────────────────
        private async Task<string> BuildRows(string userId)
        {
            var parms = new List<SqlParameter>
            {
                new SqlParameter("userid", SqlDbType.NVarChar) { Size = 50, Value = userId }
            };

            var (dt, emsg) = await Helper.GetDataTable(
                @"SELECT CONTACT_ID, NAME, EMAIL FROM CONTACT
                   WHERE USER_ID = @userid ORDER BY NAME", parms);

            if (!string.IsNullOrEmpty(emsg) || dt == null || dt.Rows.Count == 0)
                return "<div class=\"cnt-empty\">{!No contacts yet.!}</div>";

            StringBuilder sb = new StringBuilder();
            foreach (DataRow row in dt.Rows)
            {
                string id    = row["CONTACT_ID"]?.ToString() ?? string.Empty;
                string name  = row["NAME"]?.ToString()       ?? string.Empty;
                string email = row["EMAIL"]?.ToString()      ?? string.Empty;

                sb.Append("<div class=\"cnt-row\">");
                sb.Append("<div class=\"cnt-row-main\">");
                sb.Append("<div class=\"cnt-row-name\">" + HtmlEncode(name) + "</div>");
                sb.Append("<div class=\"cnt-row-sub\">"  + HtmlEncode(email) + "</div>");
                sb.Append("</div>");
                sb.Append("<div class=\"cnt-row-act\">");
                sb.Append("<button class=\"cnt-mini\" type=\"button\" onclick=\"ContactJs.edit('"
                          + JsEscape(id) + "','" + JsEscape(name) + "','" + JsEscape(email)
                          + "')\">{!Edit!}</button>");
                sb.Append("<button class=\"cnt-mini cnt-mini-del\" type=\"button\" onclick=\"ContactJs.askDelete('"
                          + JsEscape(id) + "')\">{!Remove!}</button>");
                sb.Append("</div></div>");
            }
            return sb.ToString();
        }

        private static string JsEscape(string s)
        {
            return (s ?? string.Empty).Replace("\\", "\\\\").Replace("'", "\\'")
                                      .Replace("\r", " ").Replace("\n", " ");
        }
    }
}

Contact.html

<div class="cnt-wrap">

  <h1 class="cnt-title">{!Contacts!}</h1>

  <div class="cnt-msg cnt-msg-err" id="cnt-err" style="display:none;">
    <span id="cnt-err-msg"></span>
  </div>
  <div class="cnt-msg cnt-msg-ok" id="cnt-ok" style="display:none;">
    <span id="cnt-ok-msg"></span>
  </div>

  <div class="cnt-card">
    <input type="hidden" id="cnt-id" name="contactid" value="" />

    <div class="cnt-field">
      <label class="cnt-label" for="cnt-name">{!Name!}</label>
      <input class="cnt-input" id="cnt-name" type="text" autocomplete="off" />
    </div>

    <div class="cnt-field">
      <label class="cnt-label" for="cnt-email">{!Email!}</label>
      <input class="cnt-input" id="cnt-email" type="text"
             inputmode="email" placeholder="{!you@example.com!}" autocomplete="off" />
    </div>

    <button class="cnt-btn" id="cnt-save" type="button" onclick="ContactJs.save()">
      <span id="cnt-save-label">{!Save!}</span>
    </button>
    <button class="cnt-btn cnt-btn-ghost" type="button" onclick="ContactJs.clear()">{!Clear!}</button>
  </div>

  <div class="cnt-list" id="cnt-rows">{plhd_rows}</div>

</div>

<div class="cnt-modal" id="cnt-confirm">
  <div class="cnt-modal-box">
    <div class="cnt-modal-head" id="cnt-confirm-msg">{!Remove this contact?!}</div>
    <input type="hidden" id="cnt-delid" value="" />
    <div class="cnt-modal-act">
      <button class="cnt-btn cnt-btn-ghost" type="button" onclick="ContactJs.closeConfirm()">{!Cancel!}</button>
      <button class="cnt-btn cnt-btn-del" type="button" onclick="ContactJs.confirmDelete()">{!Remove!}</button>
    </div>
  </div>
</div>

Contact.css

body { margin: 0; }

.cnt-wrap, .cnt-wrap *, .cnt-modal, .cnt-modal * { box-sizing: border-box; }

.cnt-wrap   { max-width: 720px; margin: 0 auto; padding: 24px 18px 60px;
              font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
              color: #191815; }
.cnt-title  { font-size: 22px; font-weight: 800; margin: 0 0 18px; }

.cnt-card   { padding: 18px; border: 1px solid #E4E0D3; border-radius: 12px;
              background: #fff; margin-bottom: 18px; }
.cnt-field  { margin-bottom: 13px; }
.cnt-label  { display: block; margin-bottom: 6px; font-size: 12px;
              font-weight: 600; color: #56544E; }
.cnt-input  { width: 100%; padding: 11px 13px; border: 1px solid #E4E0D3;
              border-radius: 8px; font-family: inherit; font-size: 16px; outline: none; }
.cnt-input:focus { border-color: #D97757; box-shadow: 0 0 0 3px rgba(217,119,87,0.14); }

.cnt-btn    { padding: 11px 18px; border: none; border-radius: 8px; background: #D97757;
              font-family: inherit; font-size: 13.5px; font-weight: 600;
              color: #fff; cursor: pointer; }
.cnt-btn:disabled     { opacity: .6; cursor: default; }
.cnt-btn-ghost        { border: 1px solid #E4E0D3; background: #fff; color: #56544E; }
.cnt-btn-del          { background: #C0392B; }

.cnt-msg      { margin-bottom: 14px; padding: 10px 12px; border-radius: 8px; font-size: 12.5px; }
.cnt-msg-err  { border: 1px solid #F0C6BA; background: #FDE8E8; color: #A8412A; }
.cnt-msg-ok   { border: 1px solid #CFE3CE; background: #EAF5E9; color: #3D6B3A; }

.cnt-list     { display: flex; flex-direction: column; gap: 8px; }
.cnt-row      { display: flex; align-items: center; justify-content: space-between;
                gap: 12px; padding: 13px 15px; border: 1px solid #E4E0D3;
                border-radius: 10px; background: #fff; }
.cnt-row-name { font-size: 13.5px; font-weight: 600; }
.cnt-row-sub  { margin-top: 2px; font-size: 12px; color: #8C897F; word-break: break-all; }
.cnt-row-act  { display: flex; flex: 0 0 auto; gap: 6px; }
.cnt-mini     { padding: 6px 12px; border: 1px solid #E4E0D3; border-radius: 7px;
                background: #fff; font-family: inherit; font-size: 11.5px;
                font-weight: 600; color: #56544E; cursor: pointer; }
.cnt-mini-del:hover { border-color: #E7B7AC; background: #FDE8E8; color: #A8412A; }
.cnt-empty    { padding: 26px 16px; border: 1px dashed #E4E0D3; border-radius: 10px;
                text-align: center; font-size: 12.5px; color: #A9A597; }

.cnt-modal      { display: none; position: fixed; inset: 0; z-index: 80;
                  align-items: center; justify-content: center; padding: 20px;
                  background: rgba(25,24,21,0.45); }
.cnt-modal-box  { width: 100%; max-width: 340px; padding: 20px;
                  border-radius: 14px; background: #F7F5EF; }
.cnt-modal-head { margin-bottom: 16px; font-size: 15px; font-weight: 700; }
.cnt-modal-act  { display: flex; gap: 8px; }

Contact.js

var ContactJs = (function () {

    var TXT = null;
    function t(k) {
        if (!TXT) { TXT = $GetVarData('ContactText'); }
        return (TXT && TXT[k]) ? TXT[k] : '';
    }

    function val(id)  { var e = document.getElementById(id); return e ? e.value : ''; }
    function set(id, v) { var e = document.getElementById(id); if (e) e.value = v; }
    function show(id) { var e = document.getElementById(id); if (e) e.style.display = ''; }
    function hide(id) { var e = document.getElementById(id); if (e) e.style.display = 'none'; }
    function txt(id, s) { var e = document.getElementById(id); if (e) e.textContent = s; }
    function showModal(id) { var e = document.getElementById(id); if (e) e.style.display = 'flex'; }

    function busy(on) {
        var b = document.getElementById('cnt-save');
        var l = document.getElementById('cnt-save-label');
        if (b) b.disabled = on;
        if (l) l.textContent = on ? t('saving') : t('btn_save');
    }

    // ── actions ─────────────────────────────────────────────
    function save() {
        hide('cnt-err'); hide('cnt-ok');

        var name = val('cnt-name').trim();
        if (!name) { onError('err_name'); return; }

        var email = val('cnt-email').trim();
        if (email && (email.indexOf('@') < 0 || email.indexOf('.') < 0)) { onError('err_email'); return; }

        busy(true);
        $WaitOn();
        $ApiRequest('Save', null);   // the form travels in the envelope
    }

    function edit(id, name, email) {
        set('cnt-id', id); set('cnt-name', name); set('cnt-email', email);
        hide('cnt-err'); hide('cnt-ok');
        var f = document.getElementById('cnt-name');
        if (f) f.focus();
    }

    function clear() {
        set('cnt-id', ''); set('cnt-name', ''); set('cnt-email', '');
        hide('cnt-err'); hide('cnt-ok');
    }

    function askDelete(id) {
        set('cnt-delid', id);
        txt('cnt-confirm-msg', t('ask_delete'));
        showModal('cnt-confirm');
    }

    function closeConfirm() { hide('cnt-confirm'); }

    function confirmDelete() {
        hide('cnt-confirm');
        $WaitOn();
        $ApiRequest('Delete', JSON.stringify([
            { key: 'contactid', vlu: val('cnt-delid') }
        ]));
    }

    // ── server callbacks ────────────────────────────────────
    function onError(key) {
        busy(false);
        hide('cnt-ok');
        txt('cnt-err-msg', t(key) || t('err_generic'));
        show('cnt-err');
    }

    function onSaved() {
        busy(false);
        hide('cnt-err');
        txt('cnt-ok-msg', t('ok_saved'));
        show('cnt-ok');
        clear();
    }

    function onDeleted() {
        hide('cnt-err');
        txt('cnt-ok-msg', t('ok_deleted'));
        show('cnt-ok');
    }

    function reveal() {
        var f = document.getElementById('cnt-name');
        if (f) setTimeout(function () { f.focus(); }, 200);
    }

    return {
        reveal:        function ()          { reveal(); },
        save:          function ()          { save(); },
        edit:          function (i, n, e)   { edit(i, n, e); },
        clear:         function ()          { clear(); },
        askDelete:     function (i)         { askDelete(i); },
        closeConfirm:  function ()          { closeConfirm(); },
        confirmDelete: function ()          { confirmDelete(); },
        onError:       function (k)         { onError(k); },
        onSaved:       function ()          { onSaved(); },
        onDeleted:     function ()          { onDeleted(); }
    };

})();

document.addEventListener('DOMContentLoaded', function () { ContactJs.reveal(); });

The round trips, annotated

GET /Contact

1. Constructor: Translation = true, dictionary loaded for target Contact.
2. OnInit (in WebBase) checks the session.
3. OnInitialized reads the rows, builds the fragment, replaces {plhd_rows}, queues ContactText.
4. Render: skynet.core.js, Contact.css, Contact.js injected.
5. OnAfterRender: every {!…!} in the document is resolved.
6. Document arrives → Contact.js evaluates → InitialScripts run → $VarData.ContactText populated.

Clicking Save

1. ContactJs.save() validates locally, disables the button, raises the spinner.
2. $ApiRequest('Save', null) — no payload at all. The envelope already carries contactid, cnt-name and cnt-email.
3. Server: GetDataValue reads them, validates again, inserts or updates.
4. Response: SetElementContents("cnt-rows", …) then ExecuteScript("ContactJs.onSaved();") — in that order.
5. TranslateApiResponse resolves any tokens in the fragment.
6. Client: the list is replaced, then onSaved re-enables the button, shows the message and clears the form.

Clicking Remove

1. askDelete(id) stores the id in a hidden field and opens the page-local modal with display:flex.
2. confirmDelete() sends the id explicitly — it is action-specific, not form state.
3. Server deletes with both CONTACT_ID and USER_ID in the WHERE clause.
4. Same response shape: rows replaced, then callback.

The dictionary seed

-- one idempotent INSERT per distinct {!token!} in Contact.html and Contact.cs
IF NOT EXISTS (SELECT 1 FROM XYSDICT
               WHERE TARGET = N'Contact' AND ISOCODE = N'en-US' AND KEYWORD = N'Contacts')
    INSERT INTO XYSDICT (TARGET, ISOCODE, KEYWORD, TRANSLATED)
    VALUES (N'Contact', N'en-US', N'Contacts', N'Contacts');

IF NOT EXISTS (SELECT 1 FROM XYSDICT
               WHERE TARGET = N'Contact' AND ISOCODE = N'en-US' AND KEYWORD = N'Please enter a name.')
    INSERT INTO XYSDICT (TARGET, ISOCODE, KEYWORD, TRANSLATED)
    VALUES (N'Contact', N'en-US', N'Please enter a name.', N'Please enter a name.');

-- ... one per token ...

Conventions & Gotchas

The house rules, the security rules, the checks worth running before every delivery, and the failures that catch everyone at least once.

House rules

Security rules

Verification checklist

The framework's cross-boundary contracts are plain strings, so nothing tells you at compile time that a server call names a JavaScript function that no longer exists. These checks are cheap to automate and catch almost everything that would otherwise surface at runtime.

Parity checks — the ones that actually find bugs

Gotchas

Engine

Data transfer

Server

Structure

Review questions

Before a page is done, five questions catch most of what the automated checks cannot:

1. Is every SQL value a parameter, and is every query scoped by owner?
2. Is every value spliced into markup encoded, and every value in a script string escaped?
3. Does every error path leave the UI usable — button re-enabled, spinner cleared, message shown?
4. Is there a user-visible string literal anywhere in the .js? If so it can never be translated.
5. Does the page work when the data is empty, when the session has expired, and when the write fails?

Quick Reference

Everything worth keeping within reach, on one screen. Print this section on its own if you want a desk copy.

File layout

Lifecycle order

Page skeleton

public class Page : WebBase
{
    public Page()
    {
        Translation = true;
        string n = this.GetType().ToString().Split('.').LastOrDefault() ?? this.GetType().Name;
        var d = Helper.GetPageDict(n).GetAwaiter().GetResult();
        if (d != null && d.Count > 0) HtmlTranslator.Add(d);
    }

    public override async Task OnInitialized()
    {
        HtmlDoc.SetTitle("…");
        HtmlDoc.HtmlBodyText = HtmlDoc.HtmlBodyText.Replace("{plhd_x}", HtmlEncode(x));
        HtmlDoc.InitialScripts.SetVariableData("PageText", new { k = "{!v!}" }, HtmlTranslator);
    }

    public async Task<ApiResponse> Save()
    {
        ApiResponse r = new ApiResponse();
        // … work …
        r.SetElementContents("pfx-rows", html);
        r.ExecuteScript("PageJs.onSaved();");
        return TranslateApiResponse(r);
    }
}

var PageJs = (function () {
    var TXT = null;
    function t(k) { if (!TXT) { TXT = $GetVarData('PageText'); } return (TXT && TXT[k]) ? TXT[k] : ''; }

    function save()    { $WaitOn(); $ApiRequest('Save', null); }
    function onSaved() { /* … */ }
    function reveal()  { /* … */ }

    return { reveal: function(){ reveal(); },
             save:   function(){ save(); },
             onSaved:function(){ onSaved(); } };
})();

document.addEventListener('DOMContentLoaded', function () { PageJs.reveal(); });

ApiResponse cheat sheet

$ cheat sheet

Opcode cheat sheet

POST envelope

Security one-liners

Pre-delivery checks

Things that bite

Briefing an assistant