@plitzi/sdk-shared 0.37.8 → 0.37.10

package/dist/types/ServerTypes.d.ts

@@ -6,6 +6,7 @@ import { SSRRealtimeConfig } from './RealtimeTypes';
 import { Schema } from './SchemaTypes';
 import { AnalyticsConfig, OfflineDataRaw } from './SdkTypes';
 import { FontHead, Style } from './StyleTypes';
+import { FlagOverrides } from '../flags/resolveFlags';
 import { SpaceChange } from '../history/types';
 import { IncomingHttpHeaders } from 'node:http';
 import { FC } from 'react';
@@ -153,6 +154,24 @@ export type SSRTemplateProps = {
      */
     fonts?: FontHead;
 };
+/**
+ * Remote pictures this server fetches, resizes and keeps, at `/_plitzi/img`.
+ *
+ * A picture from a dozen other sites, some 1500 px wide for a 360 px card, is the heaviest part of most pages; with
+ * this on, an `image` whose `src` is another site's offers the browser a `srcset` of sizes this server makes — in
+ * AVIF or WebP when the browser takes them, and with `sharp` installed (without it the picture is passed through,
+ * still cached).
+ */
+export type SSRImagesConfig = {
+    /**
+     * The hosts a picture may come from: `images.example.com`, or `*.example.com` for every subdomain. Nothing else is
+     * fetched — the endpoint is otherwise a way to make this server download anything — and each address is also held
+     * to the rule every outbound request is (no private network, every redirect judged).
+     */
+    domains: readonly string[];
+    /** Where the resized files are kept. Default: `.plitzi/images` under the working directory. */
+    cacheDir?: string;
+};
 /**
  * How a store-relative font path becomes a URL a browser can fetch.
  *
@@ -256,6 +275,13 @@ export type SSRSpaceDeployment = {
     credential?: SSRCredential;
     spaceId?: number | null;
     revision?: number;
+    /**
+     * What this space's feature flags are at, for a deployment that keeps them apart from its revisions — a hash that
+     * changes exactly when they do. Part of every cache key a render is kept under (the page, its server data, the space
+     * read for it), so a flag turned in production reaches the next request while the revision stays the same. Absent,
+     * the flags change only with the revision, and the revision alone keys the caches.
+     */
+    flagsVersion?: string;
     /**
      * This render is an author looking at their own work — the builder's preview — rather than a visitor being
      * served. Metering skips it: nobody should be billed for editing.
@@ -489,6 +515,12 @@ export interface SSRRscContext {
      * doing so. Awaiting this joins the read already under way; it never starts a second one.
      */
     loadOfflineData: () => Promise<OfflineDataRaw | undefined>;
+    /**
+     * What the layers above the space decide about its flags for this request: the server's own and, on a page allowed
+     * to debug, a tester's. An element gated off by a flag is not resolved — `resolveRscData` resolves the flags
+     * against the page it matched and skips it — so a feature that is off puts nothing in the payload.
+     */
+    flagOverrides?: FlagOverrides;
 }
 /**
  * Which published version of a space is asking.
@@ -520,6 +552,8 @@ export type ActionLookupsConfig = {
     getConnector?: (spaceId: number, connectorId: string, at?: SpaceRevision) => Promise<unknown>;
     /** The space's own functions as of that revision — `SpaceFunctions` in `@plitzi/sdk-server/functions`. */
     getFunctions?: (spaceId: number, at?: SpaceRevision) => Promise<unknown>;
+    /** The feature flags the space declares as of that revision — what a flow reads as `{{ flags.<name> }}`. */
+    getFlags?: (spaceId: number, at?: SpaceRevision) => Promise<Schema['flags']>;
 };
 export type SSRActionConfig = {
     /** URL path for the write endpoint, and the base for the action-addressed routes. Defaults to '/_action'. */
@@ -876,6 +910,17 @@ export type SSRServerConfig = {
      *  so does a space whose settings switched `devTools` on. Set, it decides for every space: `false` is a refusal
      *  no space can turn around. */
     debugMode?: boolean;
+    /**
+     * The feature flags this deployment decides, by name — the `server` layer: above what each space declares, below
+     * the SDK embedding a page and a tester with the dev tools. Only for flags a space declares; an override of one it
+     * does not is ignored, and the page says so in its console.
+     *
+     * A function when one server renders several spaces and they do not share their flags: it is asked per render.
+     */
+    flags?: Record<string, boolean> | ((space: {
+        spaceId: number;
+        environment: Environment;
+    }) => Record<string, boolean>);
     cacheTtlMs?: number;
     loginPath?: string | false;
     middlewares?: SSRMiddleware[];
@@ -905,6 +950,8 @@ export type SSRServerConfig = {
     allowPrivatePluginHosts?: boolean;
     /** Where this deployment serves the font files a space uploaded — see {@link SSRFontsConfig}. */
     fonts?: SSRFontsConfig;
+    /** Remote pictures resized by this server — see {@link SSRImagesConfig}. Absent, images keep their own `src`. */
+    images?: SSRImagesConfig;
     /** Omit client-side JS from the rendered page — useful for verifying SSR HTML without hydration. Default: false. */
     ssrOnly?: boolean;
     /** Stream HTML to the client as React renders, reducing TTFB. Default: false. */

package/dist/types/SnippetTypes.d.ts

@@ -0,0 +1,28 @@
+import { Element, Schema } from './SchemaTypes';
+import { Style, StyleVariables } from './StyleTypes';
+/**
+ * A published snippet: a subtree, the style that dresses it, and the element a builder instantiates.
+ *
+ * The artefact someone hosts when they are not building a space — fetched by URL, shown in the Resources panel,
+ * dragged onto a canvas — which is why it lives beside the schema and the style rather than with the builder's own
+ * types: it is a document, produced and consumed by processes that never open a builder.
+ */
+export type Snippet = {
+    id?: string;
+    definition: {
+        name: string;
+        description: string;
+        /** Root of what travels. Its subtree is the whole of `schema.flat`, and it answers to no parent. */
+        baseElementId: Element['id'];
+    };
+    /**
+     * Only what travels: the subtree and the variables its rules read. Nothing else of the space it was cut from — its
+     * pages, settings or components — comes along, and a builder showing or dropping it reads nothing else.
+     */
+    schema: Pick<Schema, 'flat' | 'variables'>;
+    style: Style;
+};
+/** The part of a style a snippet brings into a space: its rules, by display mode, and the tokens they read. */
+export type SnippetStyle = Pick<Style, 'platform'> & {
+    variables?: Partial<StyleVariables>;
+};

package/dist/types/SpaceTypes.d.ts

@@ -108,3 +108,39 @@ export type SpaceDeployment = {
     createdAt: number;
     updatedAt: number;
 };
+/**
+ * What one version of a space is made of: the draft (`main`) a snapshot would freeze, or a snapshot as it was frozen.
+ * Counts and names, never contents — what the builder shows before a snapshot is made, and what `plitzi create --from`
+ * says it is taking out.
+ */
+export type SpaceVersionContents = {
+    environment: Environment;
+    /** 0 for the draft. */
+    revision: number;
+    /** A snapshot's own words and moment; none for the draft. */
+    snapshot: {
+        description: string;
+        publishedAt: string;
+    } | null;
+    pages: number;
+    layouts: number;
+    /** The space's components, each its own tree — frozen with the version like the pages. */
+    components: number;
+    elements: number;
+    /** Every plugin installed, and whether the source it was built from is kept with this version. */
+    plugins: {
+        type: string;
+        source: boolean;
+    }[];
+    actions: number;
+    connectors: number;
+    /** What the space's functions declare, or none when it has none. */
+    functions: {
+        tasks: number;
+        routes: number;
+    } | null;
+    /** Its runtime, and whether the source it was packed from is kept with this version — none when it has none. */
+    runtime: {
+        source: boolean;
+    } | null;
+};

package/dist/types/StoreTypes.d.ts

@@ -5,10 +5,10 @@ import { Source } from './DataSourceTypes';
 import { QueryParams, RouteParams } from './NavigationTypes';
 import { RealtimeTransport } from './RealtimeTypes';
 import { Schema, Element } from './SchemaTypes';
-import { Segment } from './SegmentTypes';
 import { SpaceConnector } from './SpaceTypes';
 import { DisplayMode, Style, StyleState } from './StyleTypes';
 import { ColorScheme, Theme } from './ThemeTypes';
+import { FlagOverrides, FlagResolution } from '../flags/resolveFlags';
 export type RuntimeSourceValues = {
     variables?: Record<string, unknown>;
     navigation?: {
@@ -22,13 +22,24 @@ export type RuntimeSourceValues = {
         mode: Theme;
         resolved: ColorScheme;
     };
+    flags?: Record<string, boolean>;
+};
+/**
+ * The feature flags of this render: what each layer above the space says, and how every flag resolved.
+ *
+ * Top-level for the reason `rsc` is: the overrides are written at the root — by whoever mounts the SDK, by the builder
+ * forcing one — and an element scope owning `runtime` would keep a write from any depth to itself.
+ */
+export type FlagsState = {
+    overrides?: FlagOverrides;
+    /** Each declared flag's answer and the layer that gave it — what the dev tools show. The values alone are the
+     *  `flags` source. */
+    resolved?: Record<string, FlagResolution>;
 };
 export type CommonState = {
-    prevSchema?: Schema;
     schema: Schema;
     pageDefinitions: Record<string, Element>;
     style: Style;
-    segments: Record<string, Segment>;
     runtime?: {
         sources: RuntimeSourceValues & Record<string, unknown>;
         state?: Record<string, unknown>;
@@ -44,12 +55,17 @@ export type CommonState = {
     };
     sources?: Record<string, Source>;
     rsc?: RscState;
+    flags?: FlagsState;
     actions?: ActionsState;
     /** Where this origin's realtime channels answer — absent in a render with no server, where no channel opens. */
     realtime?: {
         endpoint?: string;
         transport?: RealtimeTransport;
     };
+    /** Where this origin resizes remote pictures — absent in a render with no server, where an image keeps its `src`. */
+    images?: {
+        endpoint?: string;
+    };
     render?: RenderSettings;
     /**
      * The theme, mirrored from `themeStore` so the devtools store viewer answers "which theme is this" in one line.
@@ -127,6 +143,15 @@ export type RenderSettings = {
      * has to keep in step with the document by hand.
      */
     testAttributes?: boolean;
+    /**
+     * Whether the page may write the document's head — its SEO title and description. On, as a page's own document is.
+     *
+     * Off where the page is drawn in a frame of a host whose document is not the page's: the builder's canvas. A head
+     * manager writes the head of the document its code runs in, which there is the editor's — and the builder is itself
+     * mounted in a page that manages that head, so a second manager under it rewrote the host's tags and took the
+     * builder's own stylesheet away the moment a preview showed a page with SEO.
+     */
+    ownsHead?: boolean;
 };
 /** Absent `endpoint` is the whole feature switch: a render with no server tier leaves every `serverAction` step
  *  inert instead of letting each click discover a 404. */
@@ -208,6 +233,12 @@ export type BuilderState = CommonState & {
         queryParams: QueryParams;
         hostname: string;
     };
+    /**
+     * The builder's OWN feature flags — Plitzi's, not the space's: which parts of the editor this person is shown, as the
+     * platform resolved them for them when the editor opened (`PlatformFlags` in the builder's first query). Never
+     * authored, never published.
+     */
+    platformFlags?: Record<string, boolean>;
     displayMode: DisplayMode;
     selector?: string;
     styleSelector?: string;
@@ -217,6 +248,11 @@ export type BuilderState = CommonState & {
     styleAncestor?: string;
     elementHovered?: string;
     elementSelected?: string;
+    /**
+     * The component open in the canvas instead of a page, by id. Editor-only: what the author is editing, never part
+     * of the document — the canvas, the layers and the element tools then read the component's tree.
+     */
+    componentOpen?: string;
     setHovered: (elementId?: string) => void;
     setSelected: (elementId?: string, iframeDOM?: HTMLIFrameElement | null, force?: boolean) => void;
 };

package/dist/types/StyleTypes.d.ts

@@ -149,6 +149,6 @@ export type StyleContextValue = {
     styleAddFont?: unknown;
     styleUpdateFont?: unknown;
     styleRemoveFont?: unknown;
-    styleAddTemplate?: unknown;
+    styleAddSnippet?: unknown;
     styleUpdateSettings?: unknown;
 };

package/dist/types/index.d.ts

@@ -1,12 +1,11 @@
 export * from './SchemaTypes';
 export * from './StyleTypes';
-export * from './TemplateTypes';
+export * from './SnippetTypes';
 export * from './InteractionTypes';
 export * from './PluginTypes';
 export * from './ElementTypes';
 export * from './DataSourceTypes';
 export * from './EventBridgeTypes';
-export * from './SegmentTypes';
 export * from './BuilderTypes';
 export * from './NavigationTypes';
 export * from './CollectionTypes';