@runek/core 0.5.0 → 0.10.0

package/dist/index.d.ts

@@ -1,7 +1,32 @@
 import * as react from 'react';
-import { ReactNode, ComponentType } from 'react';
+import { ComponentType, ReactNode } from 'react';
 import { KeyboardControlsEntry } from '@react-three/drei';
 
+/**
+ * The single default font bundled with Runek, for the in-world text carve-out
+ * (CONTRACT §4). It travels as a base64 `data:` URI so it ships inside the JS
+ * bundle: no separate font file to resolve, no CDN fetch, nothing for the host
+ * app to serve. A world can override it per role via `WorldData.fonts`; a text
+ * component falls back to this whenever a role is undeclared, so it always
+ * renders.
+ *
+ * Face: Pixelspace, the Runek brand pixel display font (woff2, ~8KB).
+ */
+declare const DEFAULT_FONT = "data:font/woff2;base64,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";
+/**
+ * Named font roles a world declares and text components draw from. Values are
+ * font URLs (or `data:` URIs). Mirrors {@link WorldPalette}: a world overrides
+ * the roles it cares about; the rest fall back to {@link DEFAULT_FONT}.
+ */
+interface WorldFonts {
+    /** Titles, signage, headings. */
+    display: string;
+    /** Labels, paragraphs, body copy. */
+    body: string;
+}
+/** Every role resolved to the bundled default. A world's `fonts` layers on top. */
+declare const DEFAULT_FONTS: WorldFonts;
+
 /**
  * Named color slots shared by the whole world. Components default their colors
  * to these slots, so swapping the palette re-themes every component at once —
@@ -38,7 +63,63 @@ interface WorldPalette {
 }
 declare const DEFAULT_PALETTE: WorldPalette;
 
+/**
+ * A world's resolved time-of-day, the value day/night-aware components (`Sky`,
+ * `LightRig`, `Clock`) read from `useWorld()`. A world pins a fixed `time`
+ * ("HH:MM", reproducible) or tracks a live `timezone`; either way it lands here.
+ */
+interface WorldTime {
+    /** Fractional hours in [0, 24). For a live world this is a snapshot at resolve
+     *  time; call `currentHours()` for the up-to-date value each frame. */
+    hours: number;
+    /** True when the time tracks a live clock (`timezone` or system), false when pinned. */
+    live: boolean;
+    /** IANA zone in effect, if any. Drives live reads and `Clock`'s default timezone. */
+    timezone?: string;
+}
+/** A neutral, pinned midday — the default when a world declares no time. Renders
+ *  as bright day, so a world that opts out of day/night looks unchanged. */
+declare const DEFAULT_WORLD_TIME: WorldTime;
+/** Parse "HH:MM" (24-hour) into fractional hours in [0, 24), or null if malformed. */
+declare function parseClockTime(value: string): number | null;
+/** Read the current fractional hours-of-day in `timezone` (or the local system
+ *  clock when omitted), falling back to UTC if the zone is unusable. */
+declare function clockHours(timezone?: string): number;
+/**
+ * Resolve a world's `time`/`timezone` fields into a `WorldTime`. Precedence: a
+ * valid pinned `time` wins (deterministic); else a live clock in `timezone`; else
+ * the local system clock; else UTC. A malformed `time` is ignored, not fatal.
+ */
+declare function resolveWorldTime(opts: {
+    time?: string;
+    timezone?: string;
+}): WorldTime;
+/** The fractional hours for a `WorldTime` right now: constant when pinned, the
+ *  live clock when not. Components call this each frame for a live world. */
+declare function currentHours(time: WorldTime): number;
+/** Where the sun sits for a given time-of-day, shared by `Sky` and `LightRig` so
+ *  the sky's bright spot and the cast shadows always agree. */
+interface SunState {
+    /** Direction to the sun, usable directly as a `sunPosition`. Dips below the
+     *  ground plane (`position[1] < 0`) at night. */
+    position: Vec3;
+    /** 0 at or below the horizon, rising to 1 at the zenith. */
+    elevation: number;
+    /** Whether the sun is above the horizon. */
+    day: boolean;
+}
+/**
+ * A simple time-of-day → sun position curve. The sun rises at 06:00, peaks at
+ * noon, sets at 18:00, and sits below the horizon overnight. This is a
+ * latitude/date-free model (azimuth is a plain east→west sweep); accurate solar
+ * position is deliberately out of scope (see the v0.8.0 spec).
+ */
+declare function sunState(hours: number, radius?: number): SunState;
+
 type Vec3 = [number, number, number];
+/** How the player camera frames the avatar. A world default `Player` reads when
+ *  its own `view` is unset; an explicit component `view` still wins. */
+type AvatarView = 'first' | 'third';
 /** The contract every Runek component implements. */
 interface WorldComponentProps {
     position?: Vec3;
@@ -57,12 +138,130 @@ interface WorldContextValue {
     /** Meters per unit. Components scale their geometry by this. */
     unit: number;
     gravity: Vec3;
+    /** Baseline ground level (Y, in world units). Floor-sitting and water components
+     *  default their placement to it; an explicit `position` wins. Default 0. */
+    ground: number;
     /** Resolved color slots components default their materials to. */
     palette: WorldPalette;
+    /** Resolved font roles (display, body) text components draw from. Every role
+     *  is filled (the world's overrides over the bundled default), so a text
+     *  component can read `fonts[role]` unconditionally. */
+    fonts: WorldFonts;
+    /** Resolved time-of-day. Day/night-aware components (`Sky`, `LightRig`,
+     *  `Clock`) read this; defaults to a pinned midday. */
+    time: WorldTime;
+    /** World default camera view for the player, if the world declares one. */
+    avatar?: AvatarView;
 }
 
 declare const WorldContext: react.Context<WorldContextValue>;
 
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** One contributor to a world. */
+interface WorldAuthor {
+    name: string;
+    url?: string;
+}
+/** Where a world lives, so it can be linked, forked, and contributed back to. */
+interface WorldSource {
+    /** Full web URL of the canonical repo, e.g. `https://github.com/owner/repo`.
+     *  Stored whole (not `owner/repo`) so the host is detectable for the fork flow. */
+    url: string;
+    /** Path to the world file within the repo, e.g. `public/helicon.world.json`. */
+    path?: string;
+    branch?: string;
+}
+/** A world's descriptive identity: attribution, license, and where it lives.
+ *  Everything is optional; a world with no `meta` still renders. Travels in the
+ *  world file (not tooling config) so it survives a fork. */
+interface WorldMeta {
+    title?: string;
+    description?: string;
+    /** Worlds accrue contributors, hence an array. */
+    authors?: WorldAuthor[];
+    /** Free SPDX-ish string. Components are MIT code; a world is content, so authors
+     *  often prefer a Creative Commons license for the world itself. */
+    license?: string;
+    source?: WorldSource;
+}
+/** One placed component: a registry key, its props, and optional nested children. */
+interface WorldNode {
+    /** Registry key — the component's name, e.g. "Bookshelf". */
+    type: string;
+    /** Stable identity, durable across edits and reorders. Optional in hand-authored
+     *  worlds; the editor fills it in (see `assignNodeIds`). Drives React keys,
+     *  selection, and minimal PR diffs. */
+    id?: string;
+    props?: Record<string, JsonValue>;
+    children?: WorldNode[];
+}
+/** A whole world as plain data — diffable, forkable, version-controlled like any file. */
+interface WorldData {
+    version: 1;
+    /** The world's identity (title, authors, license, source). Optional. */
+    meta?: WorldMeta;
+    unit?: number;
+    gravity?: Vec3;
+    /** Baseline ground level (Y, in units). Floor-sitting and water components default
+     *  their placement to it; an explicit `position` wins. Default 0. */
+    ground?: number;
+    /** Pinned time-of-day ("HH:MM", 24h) for a reproducible world. Drives day/night. */
+    time?: string;
+    /** IANA timezone for a live, clock-driven day/night (used when `time` is unset). */
+    timezone?: string;
+    /** World default camera view; `Player` reads it when its own `view` is unset. */
+    avatar?: AvatarView;
+    /** Color-slot overrides applied to every component in the world. */
+    palette?: Partial<WorldPalette>;
+    /** Fonts the world ships, by role (`display`, `body`). Text components draw from
+     *  these; unset roles fall back to the bundled default. Values are font URLs. */
+    fonts?: Partial<WorldFonts>;
+    fog?: WorldFog;
+    nodes: WorldNode[];
+}
+type ComponentRegistry = Record<string, ComponentType<any>>;
+/**
+ * Serialize a world to pretty JSON text with a canonical, stable key order
+ * (`version, meta, unit, gravity, ground, time, timezone, avatar, palette, fonts,
+ * fog, nodes`; each node `type, id, props, children`). Stable output means an
+ * unchanged node never churns the diff, so PR reviews show only the real change.
+ */
+declare function serializeWorld(data: WorldData): string;
+/** Parse and lightly validate world JSON text. Throws on an unsupported shape. */
+declare function parseWorld(json: string): WorldData;
+/**
+ * Return a copy of the world where every node has a stable `id`. Existing ids are
+ * preserved; missing ones are generated (unique within the world). The editor calls
+ * this on load, so edits and serialized output carry durable node identity even when
+ * the source world was hand-authored without ids.
+ */
+declare function assignNodeIds(data: WorldData): WorldData;
+
+/** A GitHub-hosted world source, parsed into the pieces the contribute URLs need. */
+interface GitHubSource {
+    owner: string;
+    repo: string;
+    branch: string;
+    path?: string;
+}
+/**
+ * Parse a `WorldSource` into its GitHub owner/repo (plus branch + path), or `null`
+ * if the source is not a github.com URL. `meta.source` stores the full web URL
+ * precisely so the host is detectable here; non-GitHub hosts fall back to "open the
+ * repo" in the UI.
+ */
+declare function parseGitHubSource(source: WorldSource | undefined): GitHubSource | null;
+/** URL that forks the world's repo on GitHub. */
+declare function forkUrl(gh: GitHubSource): string;
+/**
+ * GitHub web edit-file URL. Opening it as a non-collaborator makes GitHub auto-fork
+ * the repo and open its web editor on the fork — the zero-auth contribution path.
+ * Returns `null` when the world's file path is unknown (nothing to deep-link).
+ */
+declare function editFileUrl(gh: GitHubSource): string | null;
+
 /** Default movement bindings, matching the action names ecctrl reads. */
 declare const keyboardMap: KeyboardControlsEntry[];
 
@@ -80,47 +279,65 @@ declare const useWorld: () => WorldContextValue;
 interface WorldProps {
     unit?: number;
     gravity?: Vec3;
+    /** Baseline ground level (Y). Floor-sitting and water components default to it;
+     *  an explicit `position` still wins. Default 0. */
+    ground?: number;
     keyboardMap?: KeyboardControlsEntry[];
     /** Render the default light rig. Set false to supply your own (e.g. <LightRig>). */
     lights?: boolean;
     /** Override color slots; unset slots keep their defaults. Components read these via `useWorld()`. */
     palette?: Partial<WorldPalette>;
+    /** Fonts the world ships, by role (`display`, `body`). Text components draw from
+     *  these; unset roles fall back to the bundled default. Values are font URLs. */
+    fonts?: Partial<WorldFonts>;
     /** Linear distance fog. Pair the color with your sky's horizon. */
     fog?: WorldFog;
+    /** Pin a fixed time-of-day ("HH:MM", 24h) so the world is reproducible. Drives
+     *  day/night-aware components. A `timezone` instead makes it track a live clock. */
+    time?: string;
+    /** IANA timezone (e.g. "Asia/Kolkata") for a live, clock-driven day/night. Ignored
+     *  when `time` is set (a pin wins); used as the live source otherwise. */
+    timezone?: string;
+    /** World default camera view. `Player` reads it when its own `view` is unset. */
+    avatar?: AvatarView;
     /** Fired when a pointer click misses every object (used to deselect in the editor). */
     onPointerMissed?: () => void;
+    /** Keep the WebGL backbuffer so the canvas can be snapshotted via `toDataURL`
+     *  (the editor enables this for the "suggest changes" PNG). Off by default — it can
+     *  cost a little performance. */
+    preserveDrawingBuffer?: boolean;
     debug?: boolean;
     children?: ReactNode;
 }
-declare function World({ unit, gravity, keyboardMap, lights, palette, fog, onPointerMissed, debug, children, }: WorldProps): react.JSX.Element;
+declare function World({ unit, gravity, ground, keyboardMap, lights, palette, fonts, fog, time, timezone, avatar, onPointerMissed, preserveDrawingBuffer, debug, children, }: WorldProps): react.JSX.Element;
 
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-/** One placed component: a registry key, its props, and optional nested children. */
-interface WorldNode {
-    /** Registry key — the component's name, e.g. "Bookshelf". */
-    type: string;
-    props?: Record<string, JsonValue>;
-    children?: WorldNode[];
+interface WorldAboutProps {
+    /** The world's identity. When absent, the panel shows a minimal "untitled world". */
+    meta?: WorldMeta;
 }
-/** A whole world as plain data — diffable, forkable, version-controlled like any file. */
-interface WorldData {
-    version: 1;
-    unit?: number;
-    gravity?: Vec3;
-    /** Color-slot overrides applied to every component in the world. */
-    palette?: Partial<WorldPalette>;
-    fog?: WorldFog;
-    nodes: WorldNode[];
+/**
+ * A small `ⓘ` affordance that opens a read-only "About this world" panel over the
+ * canvas. A pure view of `meta` (title, description, authors, license, source repo)
+ * plus a "built with Runek" tag. Surfaced in both walk (`WorldRenderer`) and edit
+ * (`WorldEditor`) modes — a visitor wants to know whose world it is and how it is
+ * licensed, not just an editor.
+ */
+declare function WorldAbout({ meta }: WorldAboutProps): react.JSX.Element;
+
+interface WorldContributeProps {
+    /** The edited world. Its `meta.source` drives the GitHub URLs; its content is the download. */
+    data: WorldData;
+    onClose: () => void;
 }
-type ComponentRegistry = Record<string, ComponentType<any>>;
-/** Serialize a world to pretty JSON text. */
-declare function serializeWorld(data: WorldData): string;
-/** Parse and lightly validate world JSON text. Throws on an unsupported shape. */
-declare function parseWorld(json: string): WorldData;
+/**
+ * "Suggest changes upstream": a modal that couriers the edited world to GitHub's own
+ * UI with no account, token, or backend. Runek downloads the edited JSON + a snapshot,
+ * then opens GitHub's edit-file URL (which auto-forks for non-collaborators); the modal
+ * copy walks paste → commit → PR. Non-GitHub hosts fall back to opening the repo.
+ */
+declare function WorldContribute({ data, onClose }: WorldContributeProps): react.JSX.Element;
 
-interface WorldEditorProps extends Omit<WorldProps, 'children' | 'unit' | 'gravity' | 'palette' | 'fog'> {
+interface WorldEditorProps extends Omit<WorldProps, 'children' | 'unit' | 'gravity' | 'palette' | 'fog' | 'time' | 'timezone' | 'avatar'> {
     data: WorldData;
     registry: ComponentRegistry;
     onChange: (next: WorldData) => void;
@@ -138,11 +355,11 @@ interface WorldNodesProps {
 /** Render a list of world nodes by looking each `type` up in the registry. Recurses into children. */
 declare function WorldNodes({ nodes, registry }: WorldNodesProps): react.JSX.Element;
 
-interface WorldRendererProps extends Omit<WorldProps, 'children' | 'unit' | 'gravity' | 'palette' | 'fog'> {
+interface WorldRendererProps extends Omit<WorldProps, 'children' | 'unit' | 'gravity' | 'palette' | 'fog' | 'time' | 'timezone' | 'avatar'> {
     data: WorldData;
     registry: ComponentRegistry;
 }
 /** Render a `WorldData` object inside a `<World>`, resolving each node via the registry. */
 declare function WorldRenderer({ data, registry, ...worldProps }: WorldRendererProps): react.JSX.Element;
 
-export { type ComponentRegistry, DEFAULT_PALETTE, type JsonValue, type Rng, type Vec3, World, type WorldComponentProps, WorldContext, type WorldContextValue, type WorldData, WorldEditor, type WorldEditorProps, type WorldFog, type WorldNode, WorldNodes, type WorldNodesProps, type WorldPalette, type WorldProps, WorldRenderer, type WorldRendererProps, int, keyboardMap, parseWorld, pick, range, rng, serializeWorld, sub, useWorld };
+export { type AvatarView, type ComponentRegistry, DEFAULT_FONT, DEFAULT_FONTS, DEFAULT_PALETTE, DEFAULT_WORLD_TIME, type GitHubSource, type JsonValue, type Rng, type SunState, type Vec3, World, WorldAbout, type WorldAboutProps, type WorldAuthor, type WorldComponentProps, WorldContext, type WorldContextValue, WorldContribute, type WorldContributeProps, type WorldData, WorldEditor, type WorldEditorProps, type WorldFog, type WorldFonts, type WorldMeta, type WorldNode, WorldNodes, type WorldNodesProps, type WorldPalette, type WorldProps, WorldRenderer, type WorldRendererProps, type WorldSource, type WorldTime, assignNodeIds, clockHours, currentHours, editFileUrl, forkUrl, int, keyboardMap, parseClockTime, parseGitHubSource, parseWorld, pick, range, resolveWorldTime, rng, serializeWorld, sub, sunState, useWorld };