paraframe 0.0.0-stage → 0.1.0

package/dist/nav.d.ts

@@ -0,0 +1,18 @@
+import type { Attachment } from 'svelte/attachments';
+/** Navigation between frames, available to any component inside a frame. */
+export interface FrameNav {
+    /** Id of the frame being shown. */
+    readonly current: string;
+    /** URL that opens a frame in the player. */
+    href(frameId: string): string;
+    /** Shows another frame. */
+    go(frameId: string): void;
+    /**
+     * Turns any element into a link to another frame, e.g. a table row:
+     * `<tr {@attach nav.hotspot('detail')}>`.
+     */
+    hotspot(frameId: string): Attachment<HTMLElement>;
+}
+export declare function setFrameNav(nav: FrameNav): void;
+/** Returns frame navigation. Outside a frame host, links do nothing. */
+export declare function useFrameNav(): FrameNav;

package/dist/nav.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('paraframe.nav');
+const detached = {
+    current: '',
+    href: () => '#',
+    go: () => { },
+    hotspot: () => () => { }
+};
+export function setFrameNav(nav) {
+    setContext(KEY, nav);
+}
+/** Returns frame navigation. Outside a frame host, links do nothing. */
+export function useFrameNav() {
+    return getContext(KEY) ?? detached;
+}

package/dist/prototype.d.ts

@@ -0,0 +1,10 @@
+import type { FrameSize, Prototype, PrototypeDefinition, ResolvedFrame } from './types.js';
+export declare const DEFAULT_SIZE: FrameSize;
+/** Validates a prototype definition and indexes its frames. Throws on bad or duplicate ids. */
+export declare function definePrototype(definition: PrototypeDefinition): Prototype;
+/** Prerender entries for a `[frame]` route parameter. */
+export declare function frameEntries(prototype: Prototype): {
+    frame: string;
+}[];
+/** Imports a frame's component. Use it in the frame route's `load`. Responds 404 for unknown ids. */
+export declare function resolveFrame(prototype: Prototype, frameId: string): Promise<ResolvedFrame>;

package/dist/prototype.js

@@ -0,0 +1,77 @@
+import { error } from '@sveltejs/kit';
+export const DEFAULT_SIZE = { width: 1440, height: 900 };
+const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function assertId(kind, id) {
+    if (!ID.test(id)) {
+        throw new Error(`[paraframe] ${kind} id "${id}" must be lowercase letters, digits and dashes`);
+    }
+}
+/** Validates a prototype definition and indexes its frames. Throws on bad or duplicate ids. */
+export function definePrototype(definition) {
+    const size = { ...DEFAULT_SIZE, ...definition.size };
+    const frames = [];
+    const byId = new Map();
+    const sectionIds = new Set();
+    const sections = definition.sections.map((def) => {
+        assertId('Section', def.id);
+        if (sectionIds.has(def.id))
+            throw new Error(`[paraframe] Duplicate section id "${def.id}"`);
+        sectionIds.add(def.id);
+        const section = { id: def.id, title: def.title, columns: def.columns, frames: [] };
+        for (const f of def.frames) {
+            assertId('Frame', f.id);
+            if (byId.has(f.id))
+                throw new Error(`[paraframe] Duplicate frame id "${f.id}"`);
+            const frame = {
+                id: f.id,
+                title: f.title,
+                load: f.load,
+                props: f.props ?? {},
+                size: { ...size, ...f.size },
+                section,
+                index: frames.length
+            };
+            frames.push(frame);
+            byId.set(f.id, frame);
+            section.frames.push(frame);
+        }
+        return section;
+    });
+    const flows = (definition.flows ?? []).map((flow) => {
+        assertId('Flow', flow.id);
+        if (!byId.has(flow.start)) {
+            throw new Error(`[paraframe] Flow "${flow.id}" starts on unknown frame "${flow.start}"`);
+        }
+        return { ...flow };
+    });
+    return {
+        title: definition.title,
+        description: definition.description,
+        size,
+        sections,
+        frames,
+        flows,
+        paths: definition.paths,
+        get: (id) => byId.get(id),
+        next: (id) => {
+            const frame = byId.get(id);
+            return frame ? frames[frame.index + 1] : undefined;
+        },
+        prev: (id) => {
+            const frame = byId.get(id);
+            return frame && frame.index > 0 ? frames[frame.index - 1] : undefined;
+        }
+    };
+}
+/** Prerender entries for a `[frame]` route parameter. */
+export function frameEntries(prototype) {
+    return prototype.frames.map((f) => ({ frame: f.id }));
+}
+/** Imports a frame's component. Use it in the frame route's `load`. Responds 404 for unknown ids. */
+export async function resolveFrame(prototype, frameId) {
+    const frame = prototype.get(frameId);
+    if (!frame)
+        error(404, `No frame "${frameId}" in this prototype`);
+    const module = await frame.load();
+    return { frame, component: module.default };
+}

package/dist/styles.css

@@ -0,0 +1,133 @@
+/*
+  paraframe's chrome. Import it once in the layout of the canvas and player
+  routes, not in the frame route: frames carry the host app's own styles.
+
+  Override the --pf-* custom properties to theme the chrome.
+*/
+@import 'tailwindcss' source(none);
+@source './';
+
+:root {
+	--pf-font: ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+	--pf-ink: #292524;
+	--pf-muted: #78716c;
+	--pf-line: #d6d3d1;
+	--pf-wash: #e7e5e4;
+	--pf-surface: #f5f5f4;
+	--pf-canvas: #1c1917;
+	--pf-canvas-ink: #e7e5e4;
+	--pf-canvas-muted: #a8a29e;
+	--pf-selection: #f5f5f4;
+	--pf-section: #292524;
+	--pf-grid: rgb(168 162 158 / 0.2);
+	--pf-stage: #1c1917;
+	--pf-accent: #57534e;
+	--pf-avatar: #009aaa;
+	--pf-comment: #0d99ff;
+	--pf-comment-soft: #e5f4ff;
+	/* Comments (visual-comments) take paraframe's colours and font. */
+	--vc-comment: var(--pf-comment);
+	--vc-comment-soft: var(--pf-comment-soft);
+	--vc-avatar: var(--pf-avatar);
+	--vc-font: var(--pf-font);
+	--pf-island: rgb(50 50 50 / 0.57);
+	--pf-island-ink: #fff;
+	--pf-island-muted: rgb(255 255 255 / 0.6);
+	--pf-island-hover: rgb(255 255 255 / 0.12);
+}
+
+@theme inline {
+	--font-pf: var(--pf-font);
+	--color-pf-ink: var(--pf-ink);
+	--color-pf-muted: var(--pf-muted);
+	--color-pf-line: var(--pf-line);
+	--color-pf-wash: var(--pf-wash);
+	--color-pf-surface: var(--pf-surface);
+	--color-pf-canvas: var(--pf-canvas);
+	--color-pf-canvas-ink: var(--pf-canvas-ink);
+	--color-pf-canvas-muted: var(--pf-canvas-muted);
+	--color-pf-selection: var(--pf-selection);
+	--color-pf-section: var(--pf-section);
+	--color-pf-stage: var(--pf-stage);
+	--color-pf-accent: var(--pf-accent);
+	--color-pf-avatar: var(--pf-avatar);
+	--color-pf-comment: var(--pf-comment);
+	--color-pf-comment-soft: var(--pf-comment-soft);
+	--color-pf-island: var(--pf-island);
+	--color-pf-island-ink: var(--pf-island-ink);
+	--color-pf-island-muted: var(--pf-island-muted);
+}
+
+@layer components {
+	.pf-toolbar {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: flex-start;
+		justify-content: space-between;
+		gap: 0.5rem;
+		pointer-events: none;
+	}
+	/* Floating chrome: a frosted pill of pill-shaped tools. */
+	.pf-island {
+		display: flex;
+		min-width: 0;
+		max-width: 100%;
+		align-items: center;
+		gap: 0.125rem;
+		padding: 0.25rem;
+		border-radius: 9999px;
+		background: var(--pf-island);
+		backdrop-filter: blur(5px);
+		-webkit-backdrop-filter: blur(5px);
+		color: var(--pf-island-ink);
+		pointer-events: auto;
+	}
+	.pf-tool {
+		display: inline-flex;
+		height: 2rem;
+		min-width: 2rem;
+		align-items: center;
+		justify-content: center;
+		border-radius: 9999px;
+		color: var(--pf-island-ink);
+		outline: none;
+	}
+	.pf-tool:hover,
+	.pf-tool[aria-expanded='true'] {
+		background: var(--pf-island-hover);
+	}
+	.pf-tool:disabled {
+		opacity: 0.35;
+		pointer-events: none;
+	}
+	.pf-tool[aria-pressed='true'],
+	.pf-tool-primary {
+		background: var(--pf-island-ink);
+		color: var(--pf-ink);
+	}
+	.pf-tool-primary {
+		gap: 0.375rem;
+		padding-inline: 0.875rem 1rem;
+		font-weight: 500;
+	}
+	.pf-tool-primary:hover { background: rgb(255 255 255 / 0.85); }
+	.pf-tool:focus-visible {
+		box-shadow: 0 0 0 2px var(--pf-island-muted);
+	}
+
+	.pf-tool-light {
+		display: inline-flex;
+		height: 1.75rem;
+		min-width: 1.75rem;
+		align-items: center;
+		justify-content: center;
+		border-radius: 0.125rem;
+		outline: none;
+	}
+	.pf-tool-light:hover {
+		background: var(--pf-wash);
+	}
+	.pf-tool-light:focus-visible {
+		box-shadow: 0 0 0 2px var(--pf-accent);
+	}
+}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+import type { Component } from 'svelte';
+export type FrameComponent = Component<any>;
+/** A frame's viewport in CSS pixels. */
+export interface FrameSize {
+    width: number;
+    height: number;
+}
+export interface FrameDefinition {
+    /** URL-safe identifier: lowercase letters, digits and single dashes. */
+    id: string;
+    title: string;
+    /** Imports the frame's component, e.g. `() => import('./Overview.svelte')`. */
+    load: () => Promise<{
+        default: FrameComponent;
+    }>;
+    /** Props passed to the component, so one component can back several frames. */
+    props?: Record<string, unknown>;
+    /** Overrides the prototype's default size. */
+    size?: Partial<FrameSize>;
+}
+export interface SectionDefinition {
+    id: string;
+    title: string;
+    frames: FrameDefinition[];
+    /** Wrap frames onto a new canvas row after this many. Default: one row. */
+    columns?: number;
+}
+/** A named starting point for clicking through the prototype. */
+export interface FlowDefinition {
+    id: string;
+    title: string;
+    /** Id of the frame the flow starts on. */
+    start: string;
+}
+/**
+ * Where the host app mounts paraframe's three views. Build these with
+ * `resolve()` from `$app/paths` so base paths are respected, e.g.
+ * `play: (frame) => resolve(`play/${frame}`)`.
+ */
+export interface PrototypePaths {
+    /** The canvas with every frame. */
+    canvas: () => string;
+    /** The player, showing one frame. */
+    play: (frameId: string) => string;
+    /** A frame rendered on its own, without paraframe's chrome. Loaded inside iframes. */
+    frame: (frameId: string) => string;
+}
+export interface PrototypeDefinition {
+    title: string;
+    description?: string;
+    /** Default frame size. Default: 1440 × 900. */
+    size?: Partial<FrameSize>;
+    sections: SectionDefinition[];
+    flows?: FlowDefinition[];
+    paths: PrototypePaths;
+}
+export interface Frame {
+    id: string;
+    title: string;
+    load: FrameDefinition['load'];
+    props: Record<string, unknown>;
+    size: FrameSize;
+    section: Section;
+    /** Position in reading order across all sections. */
+    index: number;
+}
+export interface Section {
+    id: string;
+    title: string;
+    columns: number | undefined;
+    frames: Frame[];
+}
+export interface Flow {
+    id: string;
+    title: string;
+    start: string;
+}
+export interface Prototype {
+    title: string;
+    description: string | undefined;
+    size: FrameSize;
+    sections: Section[];
+    /** Every frame, in reading order. */
+    frames: Frame[];
+    flows: Flow[];
+    paths: PrototypePaths;
+    get(frameId: string): Frame | undefined;
+    /** The frame after this one in reading order, if any. */
+    next(frameId: string): Frame | undefined;
+    /** The frame before this one in reading order, if any. */
+    prev(frameId: string): Frame | undefined;
+}
+/** A frame with its component imported, ready to render. */
+export interface ResolvedFrame {
+    frame: Frame;
+    component: FrameComponent;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "paraframe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Click through Svelte prototypes like a Figma file: real Svelte components as frames, on a zoomable canvas and in a flow player.",
+  "keywords": [
+    "svelte",
+    "sveltekit",
+    "svelte5",
+    "prototype",
+    "prototyping",
+    "prototype-viewer",
+    "canvas",
+    "infinite-canvas",
+    "design-tools",
+    "figma",
+    "frames"
+  ],
+  "homepage": "https://paraframe.convex.works",
+  "bugs": "https://github.com/Convex-Works/paraframe/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Convex-Works/paraframe.git"
+  },
+  "license": "MIT",
+  "author": "Convex Works",
+  "type": "module",
+  "engines": {
+    "node": ">=22.17"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    },
+    "./comments": {
+      "types": "./dist/comments.d.ts",
+      "svelte": "./dist/comments.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "peerDependencies": {
+    "@sveltejs/kit": "^3.0.0",
+    "svelte": "^5.57.1",
+    "tailwindcss": "^4.3.0",
+    "visual-comments": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "visual-comments": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@convex-works/sign-in": "link:../sign-in",
+    "@sveltejs/adapter-static": "^4.0.0",
+    "@sveltejs/kit": "^3.0.0",
+    "@sveltejs/package": "^3.0.0",
+    "@sveltejs/vite-plugin-svelte": "^7.2.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "@types/node": "^26.6.5",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "publint": "^0.3.21",
+    "svelte": "^5.57.1",
+    "svelte-check": "^4.7.6",
+    "tailwindcss": "^4.3.0",
+    "typescript": "~6.0.3",
+    "visual-comments": "^0.1.0",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.5"
+  },
+  "imports": {
+    "#lib": "./src/lib/index.js",
+    "#lib/*": "./src/lib/*"
+  },
+  "scripts": {
+    "dev": "svelte-kit sync && svelte-package --watch",
+    "package": "svelte-kit sync && svelte-package && publint",
+    "showcase": "vite dev",
+    "build": "vite build && pnpm package",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --tsgo",
+    "test": "vitest run"
+  }
 }