@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/clientSurface.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Which part of the client an address's first page will need, so the page
+ * sent for it names that part and the browser fetches it beside the entry.
+ *
+ * The client boots in surfaces (vite.config.ts, `surfaces`): the entry
+ * decides, from the path and who-am-I, whether to draw a public page or the
+ * shell, and imports that chunk. Left to the entry, the chunk would be asked
+ * for only once the entry had run — a second round trip before anything
+ * paints. So the build writes one page per surface, each preloading its own
+ * chunk, and the server sends the one the address asks for. A guess that
+ * turns out wrong (a signed-out visitor at an App's root, sent to sign in)
+ * costs the import the entry makes anyway, never a wrong page.
+ *
+ * An App's shell page preloads the kit's shell and the App's chrome. The
+ * database browser's pages are a third: its main and the shell, and the
+ * `mistri-shell` meta that tells the entry to start that main
+ * (packages/kit/src/client/shellStart.js). The browser says so when it sends one
+ * (clientHttp.ts `ShellTitle.workbench`); an address alone never does.
+ *
+ * The paths are the client's own (packages/mistri/src/client/publicRoutes.js), and
+ * test/client-surface.test.ts holds the two readings together.
+ */
+import type { ThemeDefinition } from '../shared/theme.js';
+import { type ThemeAudiences } from '../shared/themeResolve.js';
+type ClientSurface = 'shell' | 'public' | 'workbench';
+/**
+ * An App's `ui` as far as the look its page wears goes (the App framework's
+ * shared/appModel.ts AppUi): the look it names, the one per audience, and its
+ * own themes. A first page is sent in it; nothing else of the App is read.
+ */
+interface LookChoice {
+    theme?: {
+        preset?: string;
+        for?: ThemeAudiences;
+    };
+    customThemes?: readonly ThemeDefinition[];
+}
+/** The page the build writes for each surface, under dist/client. */
+export declare const SURFACE_PAGES: Readonly<Record<ClientSurface, string>>;
+export declare function surfaceFor(pathname: string): Exclude<ClientSurface, 'workbench'>;
+/**
+ * The look sheets (`lumen`, `sage`, `brand`) an App's own look wears, so its
+ * page can ask for them beside the entry. The client fetches a look's sheet
+ * when it applies the look (visualTheme.ts) and holds the reveal until it is
+ * here, which left the sheet a second round trip behind the entry on a first
+ * visit. The App's own look is the guess: a reader who picked another wears
+ * that, and the guess costs one sheet fetched and not used. It stays out of
+ * the first-paint bundle — a preload is a request, not bytes in the entry.
+ */
+export declare function lookSheetsFor(ui: LookChoice | undefined, audience?: Audience): readonly string[];
+/**
+ * The density the App's look starts at, so the page zooms to it before its
+ * first paint (client density.js). Guessed like the sheets: a reader who
+ * picked another look, or a density of their own, wears theirs.
+ */
+export declare function lookDensityFor(ui: LookChoice | undefined, audience?: Audience): string | undefined;
+/**
+ * The scheme the App's look says (`scheme: 'dark'` or `'dark-only'`), so the first page is sent already dark
+ * (index.html's boot script stamps it before any style is read). Left to the client, which learns the theme a round
+ * trip later, a first visit painted light and flipped. Guessed like the sheets, and a reader's own stored mode still
+ * wins when the script runs.
+ */
+export declare function lookSchemeFor(ui: LookChoice | undefined, audience?: Audience): 'dark' | 'dark-only' | undefined;
+/** The grounds a page is sent for the browser's own chrome (`theme-color`, `color-scheme`): the page's colour in each
+    mode, and whether the theme is dark in both (`dark-only`). */
+export interface PageGrounds {
+    light: string;
+    dark: string;
+    scheme?: 'dark' | 'dark-only';
+}
+/** A theme's ground in each mode, the surface where it names none (a palette's page is then its panels'). */
+export declare function groundsOf(theme: ThemeDefinition): PageGrounds;
+/**
+ * The grounds the App's look wears, said in the page's head as `theme-color` and `color-scheme`, so the address bar and
+ * the overscroll are the page's colour from the first byte instead of white until a script runs. Guessed like the
+ * sheets: a reader who picked another look or mode wears theirs.
+ */
+export declare function lookGroundsFor(ui: LookChoice | undefined, audience?: Audience): PageGrounds | undefined;
+/** Who the page is for: a signed-out visitor, or a member holding these roles (`ui.theme.for`). */
+export interface Audience {
+    public?: boolean;
+    roles?: readonly string[];
+}
+/**
+ * The sheets whose face the App's look is set in, so its page can ask for
+ * the face beside the sheet. A sheet is worn for its recipes, and a theme on
+ * Sage that borrows one of Lumen's wears Lumen's sheet with its own stack:
+ * the face is preloaded only where the interface or its headings begin with it
+ * (and, for a sheet whose face is the data's own, as Ledger's monospace figures are, where the data does), never
+ * fetched for a page that would not draw a line in it.
+ */
+export declare function lookFacesFor(ui: LookChoice | undefined, audience?: Audience): readonly string[];
+/**
+ * The App's own faces in its page's head (`type.faces`, server/app/appFonts.ts):
+ * their `@font-face` rules, so a line is drawn in its face as soon as the face
+ * is here rather than once the script has declared it, and a preload of the
+ * face its headings are drawn in, so that one is fetched beside the entry
+ * instead of a round trip after the first heading is laid out. Only the worn
+ * theme's heading face is preloaded: a preload is a request every visit pays,
+ * and the rest are fetched where a line needs them. A face is the App's own
+ * file from its own origin (`font-src 'self'`), never the bundle's bytes, so it
+ * stands outside the first-paint budgets (scripts/bundle-budget.mjs). `shown`
+ * says an inside address the way the browser asks for it (shared/mount.ts).
+ */
+export declare function appFaceHead(ui: LookChoice | undefined, shown: (href: string) => string, audience?: Audience): string;
+/**
+ * The chrome's words for a reader who does not read English, preloaded beside
+ * the entry: the client asks for them before it draws its first words
+ * (messages.ts `setMessageScope`), and left to it that is one round trip more
+ * than an English reader pays. English is in the entry, so it needs nothing;
+ * a language the chrome has no words for has no chunk and so no preload.
+ */
+export declare function localePreloads(locale: string | undefined, files: Iterable<string>): string;
+/**
+ * A tenant host's shell page asks for the tenant's flows beside the entry. The shell imports them once who-am-I
+ * has said the session is a tenant's (appChrome.js `loadTenancy`), which left their fetch a round trip behind
+ * who-am-I and in front of entering; on a tenant host a signed-in session is always one. A visitor sent on to sign
+ * in costs the fetch and nothing else. The sheet says `crossorigin`, as the loader's own stylesheet link does.
+ */
+export declare function tenantPreloads(files: Iterable<string>): string;
+/**
+ * The preload links for the look sheets a page will wear, and the faces they
+ * declare, from the files the build wrote (none under the dev server). A face
+ * is otherwise asked for only once the sheet has been parsed and a line
+ * drawn in it, a round trip after the sheet; preloaded, it comes beside it.
+ */
+export declare function lookPreloads(sheets: readonly string[], files: Iterable<string>, faces?: readonly string[]): string;
+export {};

package/dist/server/clientSurface.js

@@ -0,0 +1,182 @@
+import { recipeAttributes } from '../shared/themeRecipes.js';
+import { effectiveThemeDefinition, themePreset } from '../shared/themePresets.js';
+import { resolveTheme } from '../shared/themeResolve.js';
+import { faceRules, headingFace } from '../shared/themeFaces.js';
+/** The page the build writes for each surface, under dist/client. */
+export const SURFACE_PAGES = {
+    shell: 'index.html',
+    public: 'index.public.html',
+    workbench: 'index.workbench.html',
+};
+/** A public form (`/{app}/form/{id}`, its `/status` and `/claim`), the landing for anyone (`/{app}/welcome`) or the staff door (`/{app}/sign-in`). */
+const PUBLIC = /^\/[^/@~]+\/(?:form\/[a-z0-9][a-z0-9-]{0,63}(?:\/(?:status|claim))?|welcome|sign-in)\/?$/;
+export function surfaceFor(pathname) {
+    return PUBLIC.test(pathname) ? 'public' : 'shell';
+}
+/**
+ * The look sheets (`lumen`, `sage`, `brand`) an App's own look wears, so its
+ * page can ask for them beside the entry. The client fetches a look's sheet
+ * when it applies the look (visualTheme.ts) and holds the reveal until it is
+ * here, which left the sheet a second round trip behind the entry on a first
+ * visit. The App's own look is the guess: a reader who picked another wears
+ * that, and the guess costs one sheet fetched and not used. It stays out of
+ * the first-paint bundle — a preload is a request, not bytes in the entry.
+ */
+export function lookSheetsFor(ui, audience) {
+    const theme = wornTheme(ui, audience);
+    return theme ? recipeAttributes(theme).sheets : [];
+}
+/**
+ * The density the App's look starts at, so the page zooms to it before its
+ * first paint (client density.js). Guessed like the sheets: a reader who
+ * picked another look, or a density of their own, wears theirs.
+ */
+export function lookDensityFor(ui, audience) {
+    return wornTheme(ui, audience)?.density;
+}
+/**
+ * The scheme the App's look says (`scheme: 'dark'` or `'dark-only'`), so the first page is sent already dark
+ * (index.html's boot script stamps it before any style is read). Left to the client, which learns the theme a round
+ * trip later, a first visit painted light and flipped. Guessed like the sheets, and a reader's own stored mode still
+ * wins when the script runs.
+ */
+export function lookSchemeFor(ui, audience) {
+    return wornTheme(ui, audience)?.scheme;
+}
+/** A theme's ground in each mode, the surface where it names none (a palette's page is then its panels'). */
+export function groundsOf(theme) {
+    const worn = effectiveThemeDefinition(theme, 'default');
+    const ground = (mode) => worn[mode].ground ?? worn[mode].surface;
+    return { light: ground('light'), dark: ground('dark'), ...(theme.scheme ? { scheme: theme.scheme } : {}) };
+}
+/**
+ * The grounds the App's look wears, said in the page's head as `theme-color` and `color-scheme`, so the address bar and
+ * the overscroll are the page's colour from the first byte instead of white until a script runs. Guessed like the
+ * sheets: a reader who picked another look or mode wears theirs.
+ */
+export function lookGroundsFor(ui, audience) {
+    const theme = wornTheme(ui, audience);
+    return theme ? groundsOf(theme) : undefined;
+}
+/** The theme an App's page is guessed to wear: its audience's (themeResolve.ts) without a reader's pick, which the
+    server cannot see, else the App's own look, else Workshop's. */
+function wornTheme(ui, audience = {}) {
+    if (!ui)
+        return undefined;
+    const offered = (id) => Boolean(ui.customThemes?.some((item) => item.id === id) ?? false) || Boolean(themePreset(id));
+    const { id } = resolveTheme({ ...audience, for: ui.theme?.for, preset: ui.theme?.preset, offered });
+    return ui.customThemes?.find((item) => item.id === id) ?? themePreset(id) ?? themePreset('workshop');
+}
+/** The faces each look sheet declares, by the families a stack begins with to be set in them (lumenLook.css,
+    workshopLook.css), and the files preloaded: Workshop's regular and its condensed bold, which every page draws;
+    its semibold comes when a line asks for it. */
+const SHEET_FACES = {
+    workshop: { families: ['Barlow', 'Barlow Semi Condensed'], file: /^assets\/barlow-(?:400|semi-condensed-700)-[\w-]+\.woff2$/ },
+    lumen: { families: ['Inter'], file: /^assets\/inter-latin-[\w-]+\.woff2$/ },
+    ledger: { families: ['IBM Plex Mono'], data: true, file: /^assets\/ibm-plex-mono-400-[\w-]+\.woff2$/ },
+};
+/**
+ * The sheets whose face the App's look is set in, so its page can ask for
+ * the face beside the sheet. A sheet is worn for its recipes, and a theme on
+ * Sage that borrows one of Lumen's wears Lumen's sheet with its own stack:
+ * the face is preloaded only where the interface or its headings begin with it
+ * (and, for a sheet whose face is the data's own, as Ledger's monospace figures are, where the data does), never
+ * fetched for a page that would not draw a line in it.
+ */
+export function lookFacesFor(ui, audience) {
+    const theme = wornTheme(ui, audience);
+    if (!theme)
+        return [];
+    const first = (stack) => stack
+        ?.split(',')[0]
+        ?.trim()
+        .replace(/^["']|["']$/g, '');
+    const leads = new Set([first(theme.fonts?.ui), first(theme.fonts?.heading)]);
+    const dataLead = first(theme.fonts?.data);
+    return recipeAttributes(theme).sheets.filter((sheet) => SHEET_FACES[sheet]?.families.some((family) => leads.has(family) || (SHEET_FACES[sheet]?.data && dataLead === family)));
+}
+/**
+ * The App's own faces in its page's head (`type.faces`, server/app/appFonts.ts):
+ * their `@font-face` rules, so a line is drawn in its face as soon as the face
+ * is here rather than once the script has declared it, and a preload of the
+ * face its headings are drawn in, so that one is fetched beside the entry
+ * instead of a round trip after the first heading is laid out. Only the worn
+ * theme's heading face is preloaded: a preload is a request every visit pays,
+ * and the rest are fetched where a line needs them. A face is the App's own
+ * file from its own origin (`font-src 'self'`), never the bundle's bytes, so it
+ * stands outside the first-paint budgets (scripts/bundle-budget.mjs). `shown`
+ * says an inside address the way the browser asks for it (shared/mount.ts).
+ */
+export function appFaceHead(ui, shown, audience) {
+    const theme = wornTheme(ui, audience);
+    const rules = faceRules(theme, shown);
+    if (!rules)
+        return '';
+    const heading = theme && headingFace(theme);
+    const type = heading?.href?.endsWith('.woff') ? 'font/woff' : 'font/woff2';
+    return (
+    /* A face is fetched in CORS mode, so its preload says `crossorigin`, or it is fetched twice (lookPreloads). */
+    (heading ? `    <link rel="preload" as="font" type="${type}" crossorigin href="${shown(heading.href)}">\n` : '') +
+        `    <style id="mistri-theme-faces">${rules}</style>\n`);
+}
+/** A built look sheet's file, `assets/lumenLook-<hash>.css`, by the sheet's name. */
+/** The chrome's words in one language (vite.config.ts LOCALE_GROUP): `assets/copy.es-<hash>.js`. */
+const WORDS_FILE = /^assets\/copy\.([a-z]{2,3})-[\w-]+\.js$/;
+/**
+ * The chrome's words for a reader who does not read English, preloaded beside
+ * the entry: the client asks for them before it draws its first words
+ * (messages.ts `setMessageScope`), and left to it that is one round trip more
+ * than an English reader pays. English is in the entry, so it needs nothing;
+ * a language the chrome has no words for has no chunk and so no preload.
+ */
+export function localePreloads(locale, files) {
+    const language = locale?.split('-')[0]?.toLowerCase();
+    if (!language || language === 'en')
+        return '';
+    for (const file of files)
+        if (WORDS_FILE.exec(file)?.[1] === language)
+            return `    <link rel="modulepreload" crossorigin href="/${file}">\n`;
+    return '';
+}
+/** The tenant's flows (vite.config.ts `surfaces`, `tenant`): `assets/tenant-<hash>.js` and its sheet. */
+const TENANT_FILE = /^assets\/tenant-[\w-]+\.(js|css)$/;
+/**
+ * A tenant host's shell page asks for the tenant's flows beside the entry. The shell imports them once who-am-I
+ * has said the session is a tenant's (appChrome.js `loadTenancy`), which left their fetch a round trip behind
+ * who-am-I and in front of entering; on a tenant host a signed-in session is always one. A visitor sent on to sign
+ * in costs the fetch and nothing else. The sheet says `crossorigin`, as the loader's own stylesheet link does.
+ */
+export function tenantPreloads(files) {
+    let links = '';
+    for (const file of files) {
+        const kind = TENANT_FILE.exec(file)?.[1];
+        if (kind === 'js')
+            links += `    <link rel="modulepreload" crossorigin href="/${file}">\n`;
+        else if (kind === 'css')
+            links += `    <link rel="preload" as="style" crossorigin href="/${file}">\n`;
+    }
+    return links;
+}
+const LOOK_FILE = /^assets\/([a-z]+)Look-[\w-]+\.css$/;
+/**
+ * The preload links for the look sheets a page will wear, and the faces they
+ * declare, from the files the build wrote (none under the dev server). A face
+ * is otherwise asked for only once the sheet has been parsed and a line
+ * drawn in it, a round trip after the sheet; preloaded, it comes beside it.
+ */
+export function lookPreloads(sheets, files, faces = []) {
+    if (!sheets.length)
+        return '';
+    const wanted = new Set(sheets);
+    let links = '';
+    for (const file of files) {
+        const name = LOOK_FILE.exec(file)?.[1];
+        /* `crossorigin`, as the loader's own stylesheet link is: a preload in another mode would be fetched twice. */
+        if (name && wanted.has(name))
+            links += `    <link rel="preload" as="style" crossorigin href="/${file}">\n`;
+        /* A face is always fetched in CORS mode, so its preload says `crossorigin` too, or it is fetched again. */
+        if (faces.some((sheet) => sheets.includes(sheet) && SHEET_FACES[sheet]?.file.test(file)))
+            links += `    <link rel="preload" as="font" type="font/woff2" crossorigin href="/${file}">\n`;
+    }
+    return links;
+}

package/dist/server/columnGrants.d.ts

@@ -0,0 +1,103 @@
+/**
+ * A grant over a catalog, and every check that holds a request to it: which
+ * tables and columns a reader reads and writes, the catalog pruned to them
+ * (its edges too, since a relationship can disclose a table), and each
+ * query, view, breakdown, filter and write refused where it reaches past
+ * them. The engine's, because two products hold requests to one: an App
+ * role's grant (app/appAccess.ts, which adds its rules over writes through
+ * `WriteRules`) and a connection's hidden columns (hiddenColumns.ts), which
+ * has no App in it to ask.
+ */
+import { Refusal, type Filter, type QueryRequest, type WriteTransaction, type InsertRequest, type UpdateRequest, type DeleteRequest } from '../adapters/adapter.js';
+import { type ViewDef } from '../shared/view.js';
+import { type BreakdownDef } from '../shared/breakdown.js';
+import { type DatabaseSchema } from '../shared/schema.js';
+import type { RowScope } from '../shared/rowScope.js';
+/**
+ * A reader reaching past its grant. Its name is the App's, where most
+ * refusals are met; a connection's hidden columns (hiddenColumns.ts) say
+ * which boundary answered in a refusal of their own.
+ */
+export declare class AppAccessDenied extends Refusal {
+    constructor(message?: string);
+}
+export interface ColumnGrant {
+    readable: ReadonlySet<string>;
+    writable: ReadonlySet<string>;
+    /** Of `writable`, where a generic insert may make a row (`roles.<role>.create`). Absent: all of it. */
+    creatable?: ReadonlySet<string>;
+    /** Missing entries retain unrestricted columns within the resource grants. */
+    fields?: ReadonlyMap<string, {
+        read: ReadonlySet<string>;
+        write: ReadonlySet<string>;
+    }>;
+    /** Columns read and written by the server for its own work (a file's object
+        and hash): never listed in a served catalog, and refused to every request
+        but the server's own (`serverRequest`). */
+    internal?: ReadonlyMap<string, ReadonlySet<string>>;
+    /** Private server-owned scope. Writes require an explicit scoped transaction. */
+    rows?: RowScope;
+}
+/** Preserve changes made before invocation, never changes during its awaits.
+ * These copied sets stay private; freezing a Set alone would not freeze grants. */
+export declare function captureGrant<G extends ColumnGrant>(grant: G): G;
+export declare function markStableGrant<T extends ColumnGrant>(grant: T): T;
+/** Test-only: how many times a catalog was pruned rather than reused. */
+export declare const pruneCounters: {
+    pruned: number;
+};
+/** Hide graph edges as well as tables: a relationship can disclose another resource. */
+export declare function accessibleSchema(schema: DatabaseSchema, access: ColumnGrant): DatabaseSchema;
+/** Capture data before checking it: queued adapters must execute what we authorized.
+ * Getters, inherited properties and coercible objects are not structured requests. */
+export declare function requestData<T>(value: T, ancestors?: Set<object>): T;
+/** Every read and write check against one grant, over the catalog it prunes: an App role's (app/appAccess.ts) and a connection's hidden columns (hiddenColumns.ts) alike. */
+export declare function resourceChecks(full: DatabaseSchema, access: ColumnGrant): {
+    schema: DatabaseSchema;
+    assertRead: (table: string) => void;
+    assertWrite: (table: string) => void;
+    assertAllFields: (table: string, mode?: 'read' | 'write', owned?: boolean) => void;
+    assertParentReads: (table: string, values: Readonly<Record<string, unknown>> | undefined, insert: boolean) => void;
+    recordFields: (table: string, record: object, mode: 'read' | 'write', server?: boolean) => void;
+    keyFields: (table: string, key: object) => void;
+    queryFor: (input: QueryRequest) => {
+        table: string;
+        orderBy?: {
+            column: string;
+            direction: 'asc' | 'desc';
+        }[];
+        limit: number;
+        offset: number;
+        binary?: true;
+        columns: string[];
+        filter: Filter | undefined;
+    };
+    filterFor: (table: string, input?: Filter, server?: boolean) => Filter | undefined;
+    viewFor: (input: ViewDef) => ViewDef;
+    breakdownFor: (input: BreakdownDef) => BreakdownDef;
+    assertRelatedWrites: (table: string, fields?: string[]) => void;
+};
+/** Pure catalog validation through the same graph boundary as runtime reads. */
+export declare function validateResourceView(schema: DatabaseSchema, access: ColumnGrant, view: ViewDef): ViewDef;
+export declare function expectedCovers(full: DatabaseSchema, request: UpdateRequest): boolean;
+export type ResourceChecks = ReturnType<typeof resourceChecks>;
+/**
+ * What a product adds to the writes a grant admits (app/appAccess.ts: an
+ * App's validation, transitions, stamps, fixed actions and what a line
+ * consumes). Each runs once the grant's own checks have passed, and writes
+ * through the transaction the checks were given; left out, the write is that
+ * transaction's own.
+ */
+export interface WriteRules<G extends ColumnGrant> {
+    /** This call's grant, kept stable across its awaits: `captureGrant`, with the product's own rules copied beside it. */
+    capture(grant: G): G;
+    /** A lock on a table the grant does not write, which the reader may still update some other way. */
+    locksUnwritable?(table: string, grant: G): boolean;
+    insert?(request: InsertRequest, grant: G, server: boolean): ReturnType<WriteTransaction['insert']>;
+    /** An update to a table outside `writable`: what answers it instead of the grant's refusal, or undefined. */
+    unwritable?(request: UpdateRequest, grant: G): ReturnType<WriteTransaction['update']> | undefined;
+    update?(request: UpdateRequest, grant: G): ReturnType<WriteTransaction['update']>;
+    remove?(request: DeleteRequest, grant: G): ReturnType<WriteTransaction['remove']>;
+}
+/** Apply the same graph-aware checks to an already-owned transaction handle. */
+export declare function authorizeColumnWrites<G extends ColumnGrant>(full: DatabaseSchema, grant: G, writer: WriteTransaction, rules?: (checks: ResourceChecks) => WriteRules<G>): WriteTransaction;