@fallen-8/studio 0.0.32

package/dist-lib/twig-C5TO7-kw.js

@@ -0,0 +1,392 @@
+var t = {
+  wordPattern: /(-?\d*\.\d\w*)|([^\`\~\!\@\$\^\&\*\(\)\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\s]+)/g,
+  comments: {
+    blockComment: ["{#", "#}"]
+  },
+  brackets: [
+    ["{#", "#}"],
+    ["{%", "%}"],
+    ["{{", "}}"],
+    ["(", ")"],
+    ["[", "]"],
+    // HTML
+    ["<!--", "-->"],
+    ["<", ">"]
+  ],
+  autoClosingPairs: [
+    { open: "{# ", close: " #}" },
+    { open: "{% ", close: " %}" },
+    { open: "{{ ", close: " }}" },
+    { open: "[", close: "]" },
+    { open: "(", close: ")" },
+    { open: '"', close: '"' },
+    { open: "'", close: "'" }
+  ],
+  surroundingPairs: [
+    { open: '"', close: '"' },
+    { open: "'", close: "'" },
+    // HTML
+    { open: "<", close: ">" }
+  ]
+}, e = {
+  defaultToken: "",
+  tokenPostfix: "",
+  ignoreCase: !0,
+  keywords: [
+    // (opening) tags
+    "apply",
+    "autoescape",
+    "block",
+    "deprecated",
+    "do",
+    "embed",
+    "extends",
+    "flush",
+    "for",
+    "from",
+    "if",
+    "import",
+    "include",
+    "macro",
+    "sandbox",
+    "set",
+    "use",
+    "verbatim",
+    "with",
+    // closing tags
+    "endapply",
+    "endautoescape",
+    "endblock",
+    "endembed",
+    "endfor",
+    "endif",
+    "endmacro",
+    "endsandbox",
+    "endset",
+    "endwith",
+    // literals
+    "true",
+    "false"
+  ],
+  tokenizer: {
+    root: [
+      // whitespace
+      [/\s+/],
+      // Twig Tag Delimiters
+      [/{#/, "comment.twig", "@commentState"],
+      [/{%[-~]?/, "delimiter.twig", "@blockState"],
+      [/{{[-~]?/, "delimiter.twig", "@variableState"],
+      // HTML
+      [/<!DOCTYPE/, "metatag.html", "@doctype"],
+      [/<!--/, "comment.html", "@comment"],
+      [/(<)((?:[\w\-]+:)?[\w\-]+)(\s*)(\/>)/, ["delimiter.html", "tag.html", "", "delimiter.html"]],
+      [/(<)(script)/, ["delimiter.html", { token: "tag.html", next: "@script" }]],
+      [/(<)(style)/, ["delimiter.html", { token: "tag.html", next: "@style" }]],
+      [/(<)((?:[\w\-]+:)?[\w\-]+)/, ["delimiter.html", { token: "tag.html", next: "@otherTag" }]],
+      [/(<\/)((?:[\w\-]+:)?[\w\-]+)/, ["delimiter.html", { token: "tag.html", next: "@otherTag" }]],
+      [/</, "delimiter.html"],
+      [/[^<{]+/]
+      // text
+    ],
+    /**
+     * Comment Tag Handling
+     */
+    commentState: [
+      [/#}/, "comment.twig", "@pop"],
+      [/./, "comment.twig"]
+    ],
+    /**
+     * Block Tag Handling
+     */
+    blockState: [
+      [/[-~]?%}/, "delimiter.twig", "@pop"],
+      // whitespace
+      [/\s+/],
+      // verbatim
+      // Unlike other blocks, verbatim ehas its own state
+      // transition to ensure we mark its contents as strings.
+      [
+        /(verbatim)(\s*)([-~]?%})/,
+        ["keyword.twig", "", { token: "delimiter.twig", next: "@rawDataState" }]
+      ],
+      { include: "expression" }
+    ],
+    rawDataState: [
+      // endverbatim
+      [
+        /({%[-~]?)(\s*)(endverbatim)(\s*)([-~]?%})/,
+        ["delimiter.twig", "", "keyword.twig", "", { token: "delimiter.twig", next: "@popall" }]
+      ],
+      [/./, "string.twig"]
+    ],
+    /**
+     * Variable Tag Handling
+     */
+    variableState: [[/[-~]?}}/, "delimiter.twig", "@pop"], { include: "expression" }],
+    stringState: [
+      // closing double quoted string
+      [/"/, "string.twig", "@pop"],
+      // interpolation start
+      [/#{\s*/, "string.twig", "@interpolationState"],
+      // string part
+      [/[^#"\\]*(?:(?:\\.|#(?!\{))[^#"\\]*)*/, "string.twig"]
+    ],
+    interpolationState: [
+      // interpolation end
+      [/}/, "string.twig", "@pop"],
+      { include: "expression" }
+    ],
+    /**
+     * Expression Handling
+     */
+    expression: [
+      // whitespace
+      [/\s+/],
+      // operators - math
+      [/\+|-|\/{1,2}|%|\*{1,2}/, "operators.twig"],
+      // operators - logic
+      [/(and|or|not|b-and|b-xor|b-or)(\s+)/, ["operators.twig", ""]],
+      // operators - comparison (symbols)
+      [/==|!=|<|>|>=|<=/, "operators.twig"],
+      // operators - comparison (words)
+      [/(starts with|ends with|matches)(\s+)/, ["operators.twig", ""]],
+      // operators - containment
+      [/(in)(\s+)/, ["operators.twig", ""]],
+      // operators - test
+      [/(is)(\s+)/, ["operators.twig", ""]],
+      // operators - misc
+      [/\||~|:|\.{1,2}|\?{1,2}/, "operators.twig"],
+      // names
+      [
+        /[^\W\d][\w]*/,
+        {
+          cases: {
+            "@keywords": "keyword.twig",
+            "@default": "variable.twig"
+          }
+        }
+      ],
+      // numbers
+      [/\d+(\.\d+)?/, "number.twig"],
+      // punctuation
+      [/\(|\)|\[|\]|{|}|,/, "delimiter.twig"],
+      // strings
+      [/"([^#"\\]*(?:\\.[^#"\\]*)*)"|\'([^\'\\]*(?:\\.[^\'\\]*)*)\'/, "string.twig"],
+      // opening double quoted string
+      [/"/, "string.twig", "@stringState"],
+      // misc syntactic constructs
+      // These are not operators per se, but for the purposes of lexical analysis we
+      // can treat them as such.
+      // arrow functions
+      [/=>/, "operators.twig"],
+      // assignment
+      [/=/, "operators.twig"]
+    ],
+    /**
+     * HTML
+     */
+    doctype: [
+      [/[^>]+/, "metatag.content.html"],
+      [/>/, "metatag.html", "@pop"]
+    ],
+    comment: [
+      [/-->/, "comment.html", "@pop"],
+      [/[^-]+/, "comment.content.html"],
+      [/./, "comment.content.html"]
+    ],
+    otherTag: [
+      [/\/?>/, "delimiter.html", "@pop"],
+      [/"([^"]*)"/, "attribute.value.html"],
+      [/'([^']*)'/, "attribute.value.html"],
+      [/[\w\-]+/, "attribute.name.html"],
+      [/=/, "delimiter.html"],
+      [/[ \t\r\n]+/]
+      // whitespace
+    ],
+    // -- BEGIN <script> tags handling
+    // After <script
+    script: [
+      [/type/, "attribute.name.html", "@scriptAfterType"],
+      [/"([^"]*)"/, "attribute.value.html"],
+      [/'([^']*)'/, "attribute.value.html"],
+      [/[\w\-]+/, "attribute.name.html"],
+      [/=/, "delimiter.html"],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@scriptEmbedded",
+          nextEmbedded: "text/javascript"
+        }
+      ],
+      [/[ \t\r\n]+/],
+      // whitespace
+      [
+        /(<\/)(script\s*)(>)/,
+        ["delimiter.html", "tag.html", { token: "delimiter.html", next: "@pop" }]
+      ]
+    ],
+    // After <script ... type
+    scriptAfterType: [
+      [/=/, "delimiter.html", "@scriptAfterTypeEquals"],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@scriptEmbedded",
+          nextEmbedded: "text/javascript"
+        }
+      ],
+      // cover invalid e.g. <script type>
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/script\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    // After <script ... type =
+    scriptAfterTypeEquals: [
+      [
+        /"([^"]*)"/,
+        {
+          token: "attribute.value.html",
+          switchTo: "@scriptWithCustomType.$1"
+        }
+      ],
+      [
+        /'([^']*)'/,
+        {
+          token: "attribute.value.html",
+          switchTo: "@scriptWithCustomType.$1"
+        }
+      ],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@scriptEmbedded",
+          nextEmbedded: "text/javascript"
+        }
+      ],
+      // cover invalid e.g. <script type=>
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/script\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    // After <script ... type = $S2
+    scriptWithCustomType: [
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@scriptEmbedded.$S2",
+          nextEmbedded: "$S2"
+        }
+      ],
+      [/"([^"]*)"/, "attribute.value.html"],
+      [/'([^']*)'/, "attribute.value.html"],
+      [/[\w\-]+/, "attribute.name.html"],
+      [/=/, "delimiter.html"],
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/script\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    scriptEmbedded: [
+      [/<\/script/, { token: "@rematch", next: "@pop", nextEmbedded: "@pop" }],
+      [/[^<]+/, ""]
+    ],
+    // -- END <script> tags handling
+    // -- BEGIN <style> tags handling
+    // After <style
+    style: [
+      [/type/, "attribute.name.html", "@styleAfterType"],
+      [/"([^"]*)"/, "attribute.value.html"],
+      [/'([^']*)'/, "attribute.value.html"],
+      [/[\w\-]+/, "attribute.name.html"],
+      [/=/, "delimiter.html"],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@styleEmbedded",
+          nextEmbedded: "text/css"
+        }
+      ],
+      [/[ \t\r\n]+/],
+      // whitespace
+      [
+        /(<\/)(style\s*)(>)/,
+        ["delimiter.html", "tag.html", { token: "delimiter.html", next: "@pop" }]
+      ]
+    ],
+    // After <style ... type
+    styleAfterType: [
+      [/=/, "delimiter.html", "@styleAfterTypeEquals"],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@styleEmbedded",
+          nextEmbedded: "text/css"
+        }
+      ],
+      // cover invalid e.g. <style type>
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/style\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    // After <style ... type =
+    styleAfterTypeEquals: [
+      [
+        /"([^"]*)"/,
+        {
+          token: "attribute.value.html",
+          switchTo: "@styleWithCustomType.$1"
+        }
+      ],
+      [
+        /'([^']*)'/,
+        {
+          token: "attribute.value.html",
+          switchTo: "@styleWithCustomType.$1"
+        }
+      ],
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@styleEmbedded",
+          nextEmbedded: "text/css"
+        }
+      ],
+      // cover invalid e.g. <style type=>
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/style\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    // After <style ... type = $S2
+    styleWithCustomType: [
+      [
+        />/,
+        {
+          token: "delimiter.html",
+          next: "@styleEmbedded.$S2",
+          nextEmbedded: "$S2"
+        }
+      ],
+      [/"([^"]*)"/, "attribute.value.html"],
+      [/'([^']*)'/, "attribute.value.html"],
+      [/[\w\-]+/, "attribute.name.html"],
+      [/=/, "delimiter.html"],
+      [/[ \t\r\n]+/],
+      // whitespace
+      [/<\/style\s*>/, { token: "@rematch", next: "@pop" }]
+    ],
+    styleEmbedded: [
+      [/<\/style/, { token: "@rematch", next: "@pop", nextEmbedded: "@pop" }],
+      [/[^<]+/, ""]
+    ]
+  }
+};
+export {
+  t as conf,
+  e as language
+};

package/dist-lib/types/api/changefeed.d.ts

@@ -0,0 +1,113 @@
+import type { InstanceConfig } from "../instances/types";
+/**
+ * Change feed consumption (feature change-feed, spec §3.7): fetch-based SSE reading of
+ * GET /changefeed with the instance's auth headers - the browser-native EventSource
+ * cannot set headers, and the API key NEVER goes into a query string (URLs leak into
+ * logs and proxies).
+ *
+ * The client recipe encoded here: fetch, then stream; on resync, re-fetch. Delivery is
+ * in-order, at-most-once per connection; whenever continuity is lost the server says so
+ * in-band with a `resync` event. Reconnects carry the last seen `id:` value as `since`
+ * (the catch-up contract), with exponential backoff. A 503 means the feed is disabled
+ * (or full) - the stream stops quietly instead of hammering the server.
+ */
+export type ChangeEventKind = "vertexCreated" | "vertexRemoved" | "edgeCreated" | "edgeRemoved" | "propertySet" | "propertyRemoved" | "resync";
+export type ChangeElementType = "vertex" | "edge";
+export type ResyncReason = "trim" | "tabulaRasa" | "load" | "delegateWrite" | "overflow" | "seekOutOfRange";
+export interface ChangeEvent {
+    /** Monotonic per process epoch, commit order. */
+    seq: number;
+    /** Commit timestamp (UTC, ISO-8601), shared by a transaction's events. */
+    ts: string;
+    kind: ChangeEventKind;
+    /** Element events only. */
+    element?: ChangeElementType;
+    /** Element id - element events only. */
+    id?: number;
+    /** Omitted when the element has no label. */
+    label?: string;
+    /** The edge's type (its edgePropertyId) - edgeCreated only. */
+    edgePropertyId?: string;
+    /** Property key - propertySet/propertyRemoved only (never the value). */
+    key?: string;
+    /** Source vertex id - edgeCreated only. */
+    source?: number;
+    /** Target vertex id - edgeCreated only. */
+    target?: number;
+    /** resync only. */
+    reason?: ResyncReason;
+}
+/** Declarative server-side filter (spec §3.4): AND across dimensions, OR within one. */
+export interface ChangeFeedFilter {
+    kinds?: ChangeEventKind[];
+    elements?: ChangeElementType[];
+    labels?: string[];
+    keys?: string[];
+}
+/** Maps a filter + catch-up position onto the comma-separated query grammar. */
+export declare function buildChangeFeedQuery(filter?: ChangeFeedFilter, since?: string): Record<string, string | undefined>;
+/** One dispatched SSE frame; `data` joins multiple data lines with \n per the SSE spec. */
+export interface SseFrame {
+    id?: string;
+    event?: string;
+    data: string;
+}
+/**
+ * Incremental SSE parser: feed it chunks (split at ANY boundary), it dispatches complete
+ * frames. Comment lines (": keepalive") and unknown fields are ignored; a blank line
+ * dispatches; \n, \r\n and \r all terminate a line.
+ */
+export declare class SseParser {
+    private readonly onFrame;
+    private buffer;
+    private id;
+    private event;
+    private dataLines;
+    constructor(onFrame: (frame: SseFrame) => void);
+    push(chunk: string): void;
+    private handleLine;
+    private dispatch;
+}
+/** Decodes one `data:` payload; null when it is not a well-formed change event. */
+export declare function parseChangeEvent(data: string): ChangeEvent | null;
+/**
+ * Why the stream stopped for good:
+ * - "aborted"     - the caller's AbortSignal fired (instance switch, unmount).
+ * - "unavailable" - the server answered 503 (feed disabled or subscriber limit); the
+ *                   caller stays in its polling behaviour, no reconnect storm.
+ * - "fatal"       - a non-retryable client error (400 bad filter, 401/403 auth).
+ */
+export type StreamCloseReason = "aborted" | "unavailable" | "fatal";
+export interface StreamChangesOptions {
+    filter?: ChangeFeedFilter;
+    /** Catch-up position for the FIRST request; reconnects carry the last seen id automatically. */
+    since?: string;
+    signal: AbortSignal;
+    /** Element events only - resync events go EXCLUSIVELY to onResync, never here. */
+    onEvent: (event: ChangeEvent) => void;
+    /** Continuity was lost - re-fetch what you display (mandatory per the contract). */
+    onResync?: (event: ChangeEvent) => void;
+    /** The stream is connected (also after a successful reconnect). */
+    onOpen?: () => void;
+    /** A transient error before a reconnect attempt; the loop handles the retry itself. */
+    onError?: (error: unknown) => void;
+    /** The stream stopped for good and will NOT reconnect. */
+    onClose?: (reason: StreamCloseReason) => void;
+    /** A reconnect is scheduled (attempt counter and the backoff delay about to be waited). */
+    onRetry?: (attempt: number, delayMs: number) => void;
+    /**
+     * Every SSE `id:` as it arrives (`epoch:seq`) - the caller's catch-up position for a
+     * FUTURE subscription (the loop already carries it across its own reconnects).
+     */
+    onFrameId?: (id: string) => void;
+    /** First reconnect delay; doubles per attempt (default 1000). */
+    initialBackoffMs?: number;
+    /** Backoff ceiling (default 30000). */
+    maxBackoffMs?: number;
+}
+/**
+ * Consumes GET /changefeed until the signal aborts, reconnecting with `since=<last id>`
+ * and exponential backoff whenever the connection drops. Resolves when the stream has
+ * stopped for good (after onClose).
+ */
+export declare function streamChanges(instance: InstanceConfig, options: StreamChangesOptions): Promise<void>;

package/dist-lib/types/api/client.d.ts

@@ -0,0 +1,81 @@
+import type { InstanceConfig } from "../instances/types";
+/**
+ * Thin, instance-bound transport for the Fallen-8 REST surface (design §2.3).
+ *
+ * Hard rules encoded here:
+ * - Routes are root-level ("/graph", "/status", ...) - never under /api/v0.1/.
+ * - Missing elements come back as 200-with-null or 204: an empty body resolves to null,
+ *   it is NOT an error.
+ * - Every failed request throws an ApiError carrying status + the server's message so the
+ *   UI can always show both (NFR: no silent failures).
+ * - Auth (lightweight, extensible): an instance's API key travels as
+ *   `Authorization: Bearer <key>` by default (the shape a future OIDC/JWT scheme reuses),
+ *   or in a named header (X-Api-Key style) when configured. Keys never leave the browser
+ *   except toward their own instance.
+ */
+/**
+ * The human-readable message from a REST error body. Fallen-8 returns every error as RFC 7807
+ * `application/problem+json` (feature api-error-envelope), which carries the message in `detail`
+ * (falling back to `title`); any other body - a plain string, an empty body, a pre-envelope
+ * server, or a JSON object without a usable `detail`/`title` - is returned unchanged. So for
+ * Fallen-8's own responses the Studio error surface always shows the server's message rather than
+ * the raw problem+json object.
+ */
+export declare function problemDetail(body: string): string;
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly url: string;
+    /**
+     * The server's human-readable message - the problem+json `detail`/`title` when the body is an
+     * RFC 7807 envelope, otherwise the raw body. For Fallen-8's own errors (always carrying a
+     * `detail`/`title`) this is a clean message, never a raw JSON object.
+     */
+    readonly body: string;
+    constructor(status: number, url: string, body: string);
+}
+export interface RequestOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "PATCH";
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+    signal?: AbortSignal;
+    /**
+     * Namespace scoping (feature graph-namespaces). "namespace" (the default) prefixes the
+     * path with /ns/{namespace} when the instance is namespace-bound - the namespace is
+     * ALWAYS explicit on the wire, "default" included. "fallen8" pins Fallen-8-level
+     * endpoints (save games, delegate validation, the /ns management routes) to their bare
+     * form regardless of binding.
+     */
+    scope?: "namespace" | "fallen8";
+}
+/**
+ * The /ns/{namespace} prefix for a namespace-bound instance; the bare path for an unbound
+ * one (pre-namespace servers and Fallen-8-level callers).
+ */
+export declare function scopedPath(instance: InstanceConfig, path: string): string;
+export declare function buildUrl(baseUrl: string, path: string, query?: RequestOptions["query"]): string;
+/**
+ * Credential headers for the SYNCHRONOUS auth kinds (none/apiKey). A `bearer` instance
+ * (feature studio-embeddable: host-supplied async token provider) cannot be served here -
+ * its token only resolves in {@link resolveAuthHeaders}, which every transport call site
+ * goes through - so it THROWS rather than returning empty headers: a new sync call site
+ * must fail loudly instead of silently sending the request unauthenticated.
+ */
+export declare function authHeaders(instance: InstanceConfig): Record<string, string>;
+/**
+ * Credential headers for ALL auth kinds - the one function transport call sites use. For
+ * `bearer` it awaits the host's token provider per request (the host caches/refreshes as it
+ * sees fit); the standalone kinds pass through {@link authHeaders} synchronously.
+ */
+export declare function resolveAuthHeaders(instance: InstanceConfig): Promise<Record<string, string>>;
+/**
+ * The single place a non-ok response becomes an {@link ApiError} (status + the server's body).
+ * Shared by {@link apiRequest} and the raw-fetch bulk endpoints so every failure looks the same.
+ */
+export declare function throwIfNotOk(response: Response, url: string): Promise<void>;
+export declare function apiRequest<T>(instance: InstanceConfig, path: string, options?: RequestOptions): Promise<T | null>;
+/**
+ * Multipart POST (feature unstructured-ingestion: the document upload). Same URL scoping,
+ * auth and error mapping as {@link apiRequest}; the browser sets the multipart boundary
+ * itself, so no Content-Type is written here.
+ */
+export declare function apiForm<T>(instance: InstanceConfig, path: string, form: FormData, options?: Pick<RequestOptions, "signal" | "scope">): Promise<T | null>;