tosijs-ui 1.16.23 → 1.16.25

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 1.16.25
+
+### Dev server
+
+- **`editableData`: folders an editor on the dev page may save to** (#3365). A level or
+  scene editor running on a dev-server page can list, read and save the project's data files
+  through `/__docstore/data`, behind the same gate as source: this machine, an edit session
+  over the tunnel, or the LAN under `trustLan`. Share links stay read-only.
+  `editableData: ['static/levels']`, or `{ dirs, extensions, commit }`. Only data formats may
+  be allowed (`.json` by default; also `.jsonc` `.json5` `.ndjson` `.txt` `.csv` `.tsv`
+  `.yaml` `.yml` `.toml`), so nothing saved there runs or renders. Dot-files and symlinks are
+  never written, nor are common configuration names (`package.json`, `tsconfig.json`,
+  `firebase.json`, `*.config.*`), though the folders you name are the real boundary. A `.json`
+  save must parse, and a save replaces the file whole. A folder outside the project, the
+  project itself, one in or around `.git` or `node_modules`, or one overlapping the build
+  output stops the server at launch. `tosijs-ui/site` exports the `EditableDataOptions` type
+  and the `DATA_EXTENSIONS` list.
+- **`commit: true` makes every save a version.** Each save is its own commit
+  (`data: save <file>`, naming who saved it), and other staged work is left alone. The
+  repository's hooks run, and each git step gets 20 seconds. Nothing is committed while the
+  repository is mid-rebase, mid-merge, cherry-picking, reverting, bisecting or on a detached
+  HEAD. `?history=<file>` lists a file's latest 100 versions and `?file=<file>&at=<commit>` reads
+  one back. A save that wrote the file but did not commit answers with `commitError` instead of
+  reporting a clean save. Each committed save waits for git, so it suits an explicit Save, not
+  autosave.
+- **`tosijs-ui/doc-system/data-client`** wraps the endpoint for an editor: `listData`,
+  `readData` (text, or `{ json: true }`, or `{ at }`), `saveData` (a string as is, anything
+  else as formatted JSON) and `dataHistory`. A refusal rejects with a `DataStoreError` carrying
+  the status, and so does a page answering for the endpoint (a static host's catch-all), so
+  `listData()` tells an editor whether to offer saving.
+- **`trustLan` can name your network**, so a committed setting trusts nobody on anyone else's:
+  `trustLan: '192.168.1.0/24'` or a list, IPv4 or IPv6. Only private addresses inside it are
+  trusted. **`TOSIJS_TRUST_LAN`** sets it for one run and wins over the config either way: `1`,
+  a network, or `0` to turn a committed setting off. A network that cannot be parsed stops the
+  server at launch, and the launch warning names who is trusted and where the setting came from.
+  A refused device outside the named networks is told so in the log, and the messages readers
+  see when the LAN is refused now suggest these forms rather than `trustLan: true`.
+- **The SPA fallback shows the page the URL names.** Was: a path with no file of its own got
+  the root page, which then asked for its assets relative to that path, got 404s and never
+  hydrated; with `home` set, a reader saw the home doc. Now the dev server serves the root page
+  with its relative URLs made root-relative (in-page `#` links still stay on the page), and
+  hydration adopts a pre-rendered article only when it is the doc being shown. Generated pages
+  stamp the article with `data-doc` for that. The asset fix is the dev server's; a static host's
+  own catch-all rewrite is unchanged.
+
+## 1.16.24
+
+`dist/iife.js` grows by about 0.2 kB gzip.
+
+- **Composition rules chain.** A rule may apply to another rule, so `un:check:square` slashes
+  the checked square, and `unCheckLock` draws instead of the placeholder. `iconSvg` reports a
+  chained rule as needing the renderer, as it does any rule. Chains stop at four rules deep,
+  which keeps a hostile icon name cheap to resolve, and a custom rule whose prefix can match
+  nothing no longer recurses. `defineIcons` may now warn about a new name that reads as a
+  chain (`unCheckFoo`); it is a warning, and your definition still wins.
+- **The icon composition demo shows the bracket form.** It printed `icons.check:square()`,
+  which is not JavaScript; a name with a `:` now shows as `icons['check:square']()`.
+- **Prettier never formats SVG files.** `*.svg` is in `.prettierignore` and a `requirePragma`
+  override, and `tosijs-format` excludes it on the command line as it does markdown. Prettier
+  has no SVG parser of its own, but an editor association or a plugin such as
+  `prettier-plugin-xml` would reflow a drawing tool's export. Adopters using `tosijs-format`
+  get the command-line exclusion. To cover editors too, add `*.svg` to `.prettierignore` and
+  `{ "files": ["*.svg"], "options": { "requirePragma": true } }` to your Prettier `overrides`.
+
+### Dev-server access
+
+- **A live example's "Save to source" is offered wherever the dev server admits the page**:
+  a LAN device under `trustLan`, or a tunnel visitor with an edit session, not only
+  `localhost`. The dev server marks the pages it serves with `editableSources` on, and an
+  example on such a page asks with a `HEAD` request when it connects, once per source file; it
+  believes only an answer carrying the dev server's own header. A deployed static site is never
+  asked.
+- **Every source write admitted by `trustLan` is logged** with the device's address, the file
+  (quoted, so a crafted name cannot forge a log line) and whether it was saved.
+- **The dev server suggests `trustLan` only to a refused device on a private network**, the
+  one case it would admit; anyone else is pointed at an edit link.
+
 ## 1.16.23
 
 - **`rule:icon` applies an icon composition rule explicitly.** A `:` marks the boundary

package/bin/format.ts

@@ -2,8 +2,8 @@
 /*
 tosijs-format — the house format step, shipped as a command (#187).
 
-    tosijs-format           eslint --fix, then prettier --write (markdown excluded)
-    tosijs-format --check   eslint, then prettier --check (markdown excluded); exit 1 on any finding
+    tosijs-format           eslint --fix, then prettier --write (markdown and SVG excluded)
+    tosijs-format --check   eslint, then prettier --check (markdown and SVG excluded); exit 1 on any finding
 
 **Prettier never touches markdown** in this stack. The rule itself lives in the Prettier
 CONFIG, where every entry point reads it (editors, lint-staged, a bare `prettier --write`):
@@ -31,10 +31,11 @@ import { parseArgv } from './resolve-site-config.ts'
 
 const { has } = parseArgv(process.argv.slice(2), {
   bin: 'tosijs-format',
-  summary: 'the house format step: eslint, then prettier (never markdown)',
+  summary:
+    'the house format step: eslint, then prettier (never markdown or SVG)',
   flags: ['check'],
   usage:
-    `  tosijs-format            eslint --fix ., then prettier --write . (markdown excluded)\n` +
+    `  tosijs-format            eslint --fix ., then prettier --write . (markdown and SVG excluded)\n` +
     `  tosijs-format --check    check only: exit 1 on anything unformatted or any lint error\n\n` +
     `Uses the project's own prettier and eslint (node_modules/.bin). ESLint runs only when the\n` +
     `project has an eslint.config.* file.`,
@@ -81,13 +82,18 @@ if (hasEslintConfig) {
   }
 }
 
-// The exclusion is the point of this command: prettier never touches markdown.
+/*
+The exclusion is the point of this command: prettier never touches markdown, or SVG.
+Prettier has no SVG parser of its own, but an editor association or a plugin
+(prettier-plugin-xml) gives it one, and an SVG is a drawing tool's export, not source to
+reflow.
+*/
 if (
   run([
     bin('prettier'),
     check ? '--check' : '--write',
     '.',
-    '!**/*.{md,markdown,mdx}',
+    '!**/*.{md,markdown,mdx,svg}',
   ]) !== 0
 ) {
   failed = true

package/dist/doc-browser.js

@@ -111,6 +111,7 @@ import { tosiLocalized } from './localize.js';
 import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
+import { LAN_REFUSAL_ADVICE } from './live-example/source-access.js';
 /*
 Does this doc contain a REAL ` ```test ` block, as opposed to mentioning one?
 
@@ -954,8 +955,18 @@ export function createDocBrowser(options) {
     };
     let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
-        if (adoptInitialContent) {
-            adoptInitialContent = false; // leave the pre-rendered HTML untouched
+        /*
+        Adopt the pre-render only if it IS this doc. The dev server's SPA fallback serves the root
+        page for a path with no file of its own, so `/guide/` can arrive holding the home page's
+        article (#3346). The generator stamps `data-doc`; a page without it predates the stamp
+        and is adopted as before.
+        */
+        const prerendered = contentElement?.dataset.doc;
+        const adopt = adoptInitialContent &&
+            (prerendered === undefined || prerendered === doc.filename);
+        adoptInitialContent = false;
+        if (adopt) {
+            // leave the pre-rendered HTML untouched
         }
         else {
             // Pass the doc's build-time tjs bakes so this client-rendered page embeds the
@@ -1291,7 +1302,7 @@ export function createDocBrowser(options) {
             window.alert('This workspace needs an invite link before it can save.\n\n' +
                 'Run `tosijs-tunnel --link` on the machine hosting it, open the link once, ' +
                 'then try again. Your edit is still here.\n\n' +
-                'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.');
+                LAN_REFUSAL_ADVICE);
         }
         else {
             // Genuinely no write endpoint (a deployed static site) — hand the file back.
@@ -1306,7 +1317,7 @@ export function createDocBrowser(options) {
             window.alert(sourceUnauthorized
                 ? 'This workspace needs an invite link before you can edit.\n\n' +
                     'Run `tosijs-tunnel --link` on the machine hosting it and open the link once.\n\n' +
-                    'If you opened this over the LAN (a `.local` or local IP address), invite links will not help: set `trustLan: true` in the site config, or use its tunnel URL instead.'
+                    LAN_REFUSAL_ADVICE
                 : `Could not load source for ${doc.path}`);
             return;
         }

package/dist/doc-system/data-client.d.ts

@@ -0,0 +1,35 @@
+export declare class DataStoreError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/** Every editable file, project-relative, newest first. */
+export declare function listData(): Promise<{
+    files: {
+        file: string;
+        size: number;
+        modified: string;
+    }[];
+}>;
+/** A file's text, or parsed JSON with `json: true`; `at` reads it as of a commit. */
+export declare function readData(file: string, options: {
+    at?: string;
+    json: true;
+}): Promise<any>;
+export declare function readData(file: string, options?: {
+    at?: string;
+    json?: false;
+}): Promise<string>;
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export declare function saveData(file: string, content: unknown): Promise<{
+    ok: true;
+    file: string;
+    commit?: string | null;
+    commitError?: string;
+}>;
+/** A file's committed versions, newest first. */
+export declare function dataHistory(file: string): Promise<{
+    commit: string;
+    date: string;
+    author: string;
+    subject: string;
+}[]>;

package/dist/doc-system/data-client.js

@@ -0,0 +1,105 @@
+/*{ "parent": "Documentation System", "order": 85 }*/
+/*#
+# data client
+
+For an editor running on a dev-server page (a level editor, a scene editor) to open and save
+the project's data files through `/__docstore/data`. Turn it on by naming the folders in the
+site config; [`editableData`](/doc-site-system/) in the doc-site system reference has the
+rules.
+
+```typescript
+// tosijs-site.config.ts
+editableData: { dirs: ['static/levels'], commit: true }
+```
+
+```typescript
+import { listData, readData, saveData, dataHistory } from 'tosijs-ui/doc-system/data-client'
+
+const { files } = await listData()
+const level = await readData('static/levels/ocean.json', { json: true })
+level.spawn = [0, 2, 0]
+const { commit } = await saveData('static/levels/ocean.json', level)
+const versions = await dataHistory('static/levels/ocean.json')
+if (versions.length > 1) {
+  const before = await readData('static/levels/ocean.json', { at: versions[1].commit })
+}
+```
+
+`saveData` writes an object as JSON (two-space indent, trailing newline) and a string as it
+is. With `commit: true` in the config each save is its own commit, and `commit` in the result
+is its hash (`null` when the save changed nothing). A save that wrote but could not commit
+(a failing hook, or a repository mid-rebase) resolves with `commitError` set rather than
+rejecting, because the file was saved. Each committed save runs git and the repository's
+hooks before it answers, so it suits an explicit Save, not autosave.
+
+**Dev server only.** Everything else rejects with a `DataStoreError` whose `status` says why:
+`501` when the server has no `editableData`, `403` when this page may not edit files here or
+the file is not editable, `400` for content it refuses (JSON that does not parse). A response
+that is not the endpoint's (a deployed site's catch-all answering with a page) rejects too, so
+`listData()` is the probe for whether to offer saving at all.
+
+File names may use letters, digits, `-`, `_`, `.`, `/` and spaces. `dataHistory` returns the
+latest 100 versions.
+*/
+const ENDPOINT = '/__docstore/data';
+export class DataStoreError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'DataStoreError';
+    }
+}
+async function ask(query, init) {
+    const response = await fetch(`${ENDPOINT}${query}`, {
+        credentials: 'same-origin',
+        ...init,
+    });
+    /*
+    The endpoint answers JSON or the file's text, never a page. An HTML answer is something
+    else's: a static host's catch-all serving its index for every path.
+    */
+    const type = response.headers.get('content-type') ?? '';
+    if (response.ok && type.includes('text/html')) {
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: answered with a page, not the data endpoint (no dev server here?)`, response.status);
+    }
+    if (!response.ok) {
+        const text = await response.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch {
+            // plain text
+        }
+        throw new DataStoreError(`${init?.method ?? 'GET'} ${ENDPOINT}${query}: ${response.status} ${message}`, response.status);
+    }
+    return response;
+}
+const q = (params) => '?' + new URLSearchParams(params).toString();
+/** Every editable file, project-relative, newest first. */
+export async function listData() {
+    return (await ask('?list')).json();
+}
+export async function readData(file, options = {}) {
+    const params = { file };
+    if (options.at)
+        params.at = options.at;
+    const text = await (await ask(q(params))).text();
+    return options.json ? JSON.parse(text) : text;
+}
+/** Save a file: a string as it is, anything else as formatted JSON. */
+export async function saveData(file, content) {
+    const text = typeof content === 'string'
+        ? content
+        : JSON.stringify(content, null, 2) + '\n';
+    return (await ask('', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ file, content: text }),
+    })).json();
+}
+/** A file's committed versions, newest first. */
+export async function dataHistory(file) {
+    return (await (await ask(q({ history: file }))).json()).versions;
+}

package/dist/doc-system/site/data-store.d.ts

@@ -0,0 +1,71 @@
+/** Formats a data folder may hold. Text only: the endpoint takes and returns strings. */
+export declare const DATA_EXTENSIONS: readonly [".json", ".jsonc", ".json5", ".ndjson", ".txt", ".csv", ".tsv", ".yaml", ".yml", ".toml"];
+/** The largest save accepted, in bytes. A level is kilobytes; this stops a runaway client. */
+export declare const MAX_DATA_BYTES: number;
+export interface EditableDataOptions {
+    /** Folders, relative to the project root. */
+    dirs: string[];
+    /** Extensions to allow, from DATA_EXTENSIONS. Default `['.json']`. */
+    extensions?: string[];
+    /** Commit each save to git, so every save is a version. Default false. */
+    commit?: boolean;
+}
+export interface DataStore {
+    root: string;
+    /** Real paths of the folders, and the names they were configured as. */
+    dirs: {
+        real: string;
+        name: string;
+    }[];
+    extensions: string[];
+    commit: boolean;
+}
+/** The folder setting, checked and resolved, or null when the project has none. Throws. */
+export declare function resolveDataStore(setting: string[] | EditableDataOptions | undefined, root: string, 
+/** The site's build output, which every build deletes and rewrites. */
+outputDir?: string): DataStore | null;
+/**
+ * The absolute path a client's file name may be read or written at, or the reason it may not.
+ * `file` is project-relative (`static/levels/ocean.json`).
+ */
+export declare function resolveDataFile(store: DataStore, file: unknown): {
+    path: string;
+    rel: string;
+} | {
+    refused: string;
+};
+/** Why `content` may not be saved as `rel`, or null. JSON must parse: a half-edit is not a level. */
+export declare function dataContentProblem(rel: string, content: unknown): string | null;
+/** Write through a temporary file and a rename, so a reader never sees half a file. */
+export declare function writeDataFile(target: string, content: string): void;
+/** Every editable file in the named folders, project-relative, newest first. */
+export declare function listDataFiles(store: DataStore): {
+    file: string;
+    size: number;
+    modified: string;
+}[];
+/** Whether `root` is in a git work tree, for `commit: true` to be checked at launch. */
+export declare function isGitWorkTree(root: string): boolean;
+/**
+ * Save a file. With `commit` on, also commit it, alone, leaving other staged work as it was:
+ * `commit` is the hash, or null when the save changed nothing. A save that wrote the file but
+ * could not commit it resolves with `commitError`, because the file WAS saved. The repository's
+ * hooks run, as for any commit; a repository mid-rebase, mid-merge, bisecting or on a detached
+ * HEAD is not committed to, since that commit would land somewhere the developer did not choose.
+ */
+export declare function saveDataFile(store: DataStore, target: {
+    path: string;
+    rel: string;
+}, content: string, savedBy: string): Promise<{
+    commit?: string | null;
+    commitError?: string;
+}>;
+/** One file's committed versions, newest first. */
+export declare function dataHistory(store: DataStore, rel: string, limit?: number): Promise<{
+    commit: string;
+    date: string;
+    author: string;
+    subject: string;
+}[]>;
+/** A file as it was at `commit`, or null if the commit is not a hash or lacks the file. */
+export declare function readDataAt(store: DataStore, rel: string, commit: string): Promise<string | null>;