stylegallery 0.1.0 → 0.1.2

package/motion/vocabulary.md

@@ -1,82 +0,0 @@
----
-type: Domain Guide
-title: Motion Vocabulary
-description: Evidence-bounded method and reference for naming observable interface motion.
-domain: motion
-lifecycle: experimental
-source_repository: https://github.com/emilkowalski/skills
-source_path: skills/animation-vocabulary/SKILL.md
-source_revision: 220e8607c90b17337d210125777b7b695f26c221
----
-
-# Motion Vocabulary
-
-Primary role: motion terminology reference.
-
-## Repository Boundary
-
-This page helps a reader name observed motion. It does not prescribe implementation, authorize motion in reusable Layout CSS, or make a product-quality judgment.
-
-The terms are implementation-neutral. A framework, operating-system behavior, or branded example may illustrate a term only when clearly labeled and separately verified.
-
-## Reusable Method
-
-1. Record what changes: presence, position, scale, shape, state, scroll relationship, or feedback.
-2. Record what coordinates the change: time, sequence, input, velocity, or viewport progress.
-3. Compare the observation with the closest term families below.
-4. Return one exact term only when the observed cues distinguish it.
-5. When multiple terms remain plausible, return ordered candidates and state the missing observation.
-6. When nothing matches, return `unknown`; do not invent a canonical winner.
-
-## Term Families
-
-| Term | Observed cues | Distinguish from | Implementation-neutral meaning | Evidence boundary |
-| --- | --- | --- | --- | --- |
-| Fade | Visibility changes without a necessary spatial path. | Reveal | A gradual visibility change. | Does not imply opacity is the implementation. |
-| Slide | The element follows a directional path into, out of, or within a region. | Shared-element transition | A positional transition without necessarily preserving identity across views. | Direction and clipping must be observed. |
-| Scale transition | Apparent size changes around an origin. | Morph | Size changes while the element's basic identity remains stable. | Does not establish the correct origin or amount. |
-| Reveal | A boundary progressively exposes content. | Fade | Visibility is controlled by an advancing edge, mask, or equivalent boundary. | The masking mechanism may be unknown. |
-| Stagger | Similar elements begin related changes at distinct offsets. | Orchestration | A repeated sequence pattern, usually across peers. | The offset value is product-specific. |
-| Orchestration | Several motion events form one coordinated sequence. | Stagger | Coordination may include different elements, jobs, and timings. | Intent must be documented, not inferred from timing alone. |
-| Crossfade | One state loses visibility while another gains it in the same region. | Morph | Identity is exchanged rather than geometrically transformed. | Overlap and source order need inspection. |
-| Shared-element transition | A recognizable element appears to retain identity between states or views. | Layout animation | Continuity connects a source representation with a destination representation. | Identity continuity is a perception claim requiring rendered evidence. |
-| Layout animation | A spatial change is visually interpolated instead of appearing instantly. | Shared-element transition | Position or size changes within the layout state of an element. | Does not endorse animating layout-triggering CSS properties. |
-| Scroll-driven motion | Progress corresponds to scroll progress. | Scroll reveal | The scroll position continuously controls progress rather than merely triggering entry. | Browser and input behavior require local testing. |
-| Parallax | Layers appear to travel at different rates during a shared movement. | Ordinary scroll | Relative speed creates a depth cue. | Depth, comfort, and reduced-motion outcomes are not guaranteed. |
-| Spring motion | Response is modeled as a target-seeking dynamic system rather than a fixed timeline. | Bounce | A spring may settle without visible overshoot. | Parameters and perceived duration remain implementation-specific. |
-| Bounce | Motion overshoots or reverses before settling. | Spring motion | Visible overshoot is the defining cue, regardless of implementation. | Playfulness and appropriateness are product judgments. |
-| Interruptible motion | New input redirects a change from its current presented state. | Restarted animation | Continuity is maintained when the target changes mid-flight. | Requires interaction evidence, not source inspection alone. |
-| Rubber-band response | Movement continues beyond a boundary with increasing resistance, then returns. | Bounce | Resistance is tied to boundary overshoot and direct manipulation. | Platform examples are not a universal physics contract. |
-| Jank | Motion visibly misses expected visual continuity. | Intentional stepped motion | The discontinuity is unintended and associated with delivery or computation limits. | Frame or performance evidence is needed to attribute cause. |
-
-## Opinionated Guidance
-
-The family ordering favors what a reader can observe before implementation details. It is useful for retrieval, but it is not a complete ontology. Add a term only after a reader task demonstrates that existing terms and aliases cannot express the distinction.
-
-## Platform-Specific Guidance
-
-Names tied to iOS, macOS, a browser API, Motion, Framer Motion, React, or a component library are examples or implementation facets. Keep the cross-platform term primary and label the platform context separately.
-
-## Unsupported Absolutes
-
-- Do not call this vocabulary authoritative outside StyleGallery.
-- Do not force the nearest term when the observation is incomplete.
-- Do not attach universal FPS, GPU, duration, easing, or reduced-motion rules to a definition.
-- Do not infer implementation technology from rendered appearance alone.
-
-## Verification Contract
-
-A vocabulary lookup should exercise exact, ambiguous, and unknown cases. Pass requires one justified term, an ordered candidate set with a stated distinction, or `unknown`; invented winners fail. A new term also requires a findability task showing the current route cannot reach an adequate term within two hops.
-
-## Source, License, And Attribution
-
-- Upstream inspiration: [animation-vocabulary/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/animation-vocabulary/SKILL.md)
-- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
-- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
-- Reuse form: independent method rewrite; upstream prose, tables, code, examples, and distinctive ordering were not retained.
-- Evidence boundary: the upstream artifact records practitioner terminology; it does not prove local performance, accessibility, usability, or quality.
-
-## IA Navigation
-
-Parent: [Motion](index.md).
-Next: [Motion Review Workflow](review-workflow.md).

package/platform-guides/apple-interaction.md

@@ -1,89 +0,0 @@
----
-type: Domain Guide
-title: Apple Interaction As A Comparative Reference
-description: Bounded comparison of Apple interaction themes with explicit web-adaptation and provenance limits.
-domain: platform-guides
-lifecycle: experimental
-source_repository: https://github.com/emilkowalski/skills
-source_path: skills/apple-design/SKILL.md
-source_revision: 220e8607c90b17337d210125777b7b695f26c221
-platform: Apple platforms
-platform_version: verify-current
-reviewed_on: 2026-07-11
----
-
-# Apple Interaction As A Comparative Reference
-
-Primary role: platform comparison guide.
-
-## Repository Boundary
-
-This page uses selected Apple-platform interaction themes as comparative questions. It does not reproduce Apple guidance, establish affiliation, prescribe imitation, or treat a native implementation value as valid for the web.
-
-Current official Apple documentation is required for Apple-specific claims. Current web standards and browser documentation are required for web adaptation. Local rendered, device, accessibility, and performance evidence is required for product conclusions.
-
-## Reusable Method
-
-For each proposed comparison:
-
-1. Name the user task, platform, OS/API version, input method, and state transition.
-2. Describe the observable behavior without branded terminology.
-3. Identify the platform convention and its current official source.
-4. Separate the reusable interaction question from native implementation details.
-5. Define the web adaptation, including unavailable or materially different capabilities.
-6. Verify the adapted behavior on its real surface and record what remains unproven.
-
-## Comparative Questions
-
-| Theme | Question to investigate | Required evidence | Boundary |
-| --- | --- | --- | --- |
-| Response | Does feedback begin close enough to input to preserve cause and effect? | Interaction recording and input-state trace | No universal latency value is implied. |
-| Direct manipulation | Does the presented state follow, cancel, and resume from user input coherently? | Repeated drag/reversal test on target input modes | One-to-one tracking is not always required. |
-| Interruption | Can new input redirect a transition without jumping or locking control? | Mid-transition retarget and reversal evidence | Springs are one option, not a requirement. |
-| Velocity continuity | Does release-to-settle behavior avoid an observable seam? | Gesture and presented-state recording | Native velocity APIs and web libraries differ. |
-| Spatial consistency | Can the reader understand where content came from and where it returns? | Before/intermediate/after render plus source/focus order | Visual path cannot override semantic order. |
-| Recoverability | Can a user cancel, reverse, undo, or safely recover where the task requires it? | Task and error-path evidence | Confirmation is not universally preferable to undo. |
-| Wayfinding | Can the interface answer location, available destinations, contents, and exit? | Navigation task evidence | Familiar platform placement may not transfer across products. |
-| Soft boundaries | Would progressive resistance communicate a limit better than a hard stop? | Comparative prototype and input/device evidence | The resistance curve is not standardized across platforms. |
-| Multimodal feedback | Do visual, audio, and haptic cues share a clear cause and useful purpose? | Device timing and accessibility evidence | Web haptics/audio are not native equivalents and may be unavailable. |
-| Adaptive presentation | Does the interface remain usable across text size, contrast, transparency, motion preference, input, and viewport changes? | Relevant preference and constraint matrix | A platform feature name does not prove web accessibility. |
-
-## Opinionated Guidance
-
-Momentum-aware settling, source-anchored transitions, progressive boundary resistance, and carefully coordinated feedback can be useful hypotheses for directly manipulated interfaces. Translucent materials, system typography, haptics, and visual delight are product and platform choices outside reusable Layout pattern CSS.
-
-## Platform-Specific Guidance
-
-- iOS/macOS gesture physics, native spring APIs, Dynamic Type, system materials, haptics, and SwiftUI/UIKit behavior must be labeled as Apple-specific.
-- Any value described as shipped by Apple requires a direct, current official source and version.
-- A web mapping must identify browser support, input differences, accessibility behavior, and fallback semantics.
-- `backdrop-filter`, the Vibration API, web media queries, and JavaScript animation libraries are not equivalents merely because they can approximate one visible effect.
-
-## Unsupported Absolutes
-
-- Do not call an upstream formula or parameter an exact Apple implementation without a primary official source.
-- Do not require direct manipulation to track one-to-one in every context.
-- Do not require audio and haptic events on one exact frame as a universal web contract.
-- Do not claim translucent chrome is generally superior to opaque structure.
-- Do not adopt a single spring configuration as a safe default across tasks.
-- Do not import a named set of Apple principles as StyleGallery's shared principles.
-- Do not infer native behavior, platform affiliation, or accessibility from visual similarity.
-
-## Verification Contract
-
-Record the official platform source and version, the web-standard or browser source for adaptation, the exact target devices and input modes, relevant user preferences, and the observed pass/fail behavior. Use a real interactive prototype for interaction claims. State explicitly when native behavior cannot be reproduced or verified on the web.
-
-Review this page when Apple changes the cited convention, the web platform changes the adaptation surface, the source revision changes, or local testing contradicts the guidance. `platform_version: verify-current` prevents this experimental page from masquerading as a version-pinned platform contract.
-
-## Source, License, And Attribution
-
-- Upstream inspiration: [apple-design/SKILL.md](https://github.com/emilkowalski/skills/blob/220e8607c90b17337d210125777b7b695f26c221/skills/apple-design/SKILL.md)
-- Snapshot: `220e8607c90b17337d210125777b7b695f26c221`
-- Upstream license: MIT, Copyright (c) 2026 Emil Kowalski.
-- Reuse form: independent method rewrite; upstream prose, tables, code, exact-value sequences, Apple/WWDC-derived expression, and quotations were not retained.
-- Evidence boundary: the upstream artifact is a practitioner interpretation and provenance record, not an official Apple or web-platform source.
-
-## IA Navigation
-
-Parent: [Platform Guides](index.md).
-Next: [Layout](../layout/index.md).

package/scripts/agent-native/events.mjs

@@ -1,113 +0,0 @@
-import { cloneAndFreeze, canonicalize, hashCanonical } from "./canonical-json.mjs";
-
-function sourceObject(value, name) {
-  if (Array.isArray(value)) return { events: value };
-  if (!value || typeof value !== "object") throw new TypeError(`${name} expects an object`);
-  return value;
-}
-
-function pick(value, ...keys) {
-  if (!value || typeof value !== "object") return undefined;
-  for (const key of keys) if (Object.hasOwn(value, key)) return value[key];
-  return undefined;
-}
-
-function eventId(event) {
-  return pick(event, "event_id", "eventId", "id", "stable_ref", "stableRef");
-}
-
-function parentIds(event) {
-  const parents = pick(event, "parents", "parent_ids", "parentIds");
-  if (parents === undefined || parents === null) return [];
-  if (!Array.isArray(parents)) throw new TypeError("event parents must be an array");
-  return [...new Set(parents.map((parent) => {
-    if (typeof parent !== "string" || parent.length === 0) throw new TypeError("event parent IDs must be non-empty strings");
-    return parent;
-  }))].sort();
-}
-
-function canonicalFreeze(value) {
-  return cloneAndFreeze(JSON.parse(canonicalize(value)));
-}
-
-function normalizeEvent(input) {
-  if (!input || typeof input !== "object" || Array.isArray(input)) throw new TypeError("event must be an object");
-  const copy = structuredClone(input);
-  const id = eventId(copy);
-  if (id !== undefined && (typeof id !== "string" || id.length === 0)) throw new TypeError("event ID must be a non-empty string");
-  const stableRef = pick(copy, "stable_ref", "stableRef");
-  const parents = parentIds(copy);
-  delete copy.eventId;
-  delete copy.event_id;
-  delete copy.parentIds;
-  delete copy.parent_ids;
-  delete copy.parents;
-  delete copy.id;
-  delete copy.stableRef;
-  delete copy.stable_ref;
-  const body = { ...copy, parents };
-  if (stableRef !== undefined) body.stable_ref = stableRef;
-  const stableId = typeof id === "string" && id.length > 0 ? id : `sg:event/${hashCanonical(body).slice("sha256:".length)}`;
-  return { event_id: stableId, parents, ...body };
-}
-
-function normalizedEvents(value) {
-  const source = sourceObject(value, "event collection");
-  const events = pick(source, "events", "items", "entries");
-  if (!Array.isArray(events)) throw new TypeError("events must be an array");
-  const result = [];
-  const byId = new Map();
-  for (const item of events) {
-    const normalized = normalizeEvent(item);
-    const id = normalized.event_id;
-    const previous = byId.get(id);
-    if (previous) {
-      if (canonicalize(previous) !== canonicalize(normalized)) throw new TypeError(`event ${id} is immutable`);
-      continue;
-    }
-    byId.set(id, normalized);
-    result.push(normalized);
-  }
-  const ids = new Set(result.map((item) => item.event_id));
-  const visiting = new Set();
-  const visited = new Set();
-  const eventById = new Map(result.map((item) => [item.event_id, item]));
-  const visit = (id) => {
-    if (visiting.has(id)) throw new TypeError(`event cycle includes ${id}`);
-    if (visited.has(id)) return;
-    visiting.add(id);
-    for (const parent of eventById.get(id).parents) if (eventById.has(parent)) visit(parent);
-    visiting.delete(id);
-    visited.add(id);
-  };
-  for (const id of ids) visit(id);
-  return result;
-}
-
-/**
- * Append one event to an immutable causal event collection. Existing IDs are
- * idempotent only when their canonical bytes are identical; a changed payload
- * is rejected rather than silently rewriting history.
- */
-export function appendEvent(input) {
-  const source = sourceObject(input, "appendEvent");
-  const existing = normalizedEvents(source);
-  const appended = normalizeEvent(pick(source, "event") ?? source);
-  const existingById = new Map(existing.map((item) => [item.event_id, item]));
-  const previous = existingById.get(appended.event_id);
-  if (previous && canonicalize(previous) !== canonicalize(appended)) throw new TypeError(`event ${appended.event_id} is immutable`);
-  if (previous) return canonicalFreeze(existing);
-  return canonicalFreeze(normalizedEvents({ events: [...existing, appended] }));
-}
-
-export const appendCausalEvent = appendEvent;
-
-/** Return the deterministic leaf IDs of an append-only causal DAG. */
-export function eventHeads(input) {
-  const events = normalizedEvents(input);
-  const ids = new Set(events.map((item) => item.event_id));
-  const referenced = new Set(events.flatMap((item) => item.parents.filter((parent) => ids.has(parent))));
-  return canonicalFreeze([...ids].filter((id) => !referenced.has(id)).sort());
-}
-
-export const getEventHeads = eventHeads;

package/scripts/agent-native/immutable-store.mjs

@@ -1,102 +0,0 @@
-import { canonicalize, cloneAndFreeze, deepFreeze } from "./canonical-json.mjs";
-import { parseStableRef, parseVersionId } from "./identity.mjs";
-
-export class ImmutableStoreError extends TypeError {
-  constructor(code, message, path = "") {
-    super(message);
-    this.name = "ImmutableStoreError";
-    this.code = code;
-    if (path) this.path = path;
-  }
-}
-
-function fail(code, message, path) {
-  throw new ImmutableStoreError(code, message, path);
-}
-
-function recordRef(record) {
-  const stable_ref = record?.stable_ref ?? record?.stableRef;
-  const version_id = record?.version_id ?? record?.versionId;
-  if (typeof stable_ref !== "string") fail("store_stable_ref_required", "append requires a StableRef", "stable_ref");
-  if (typeof version_id !== "string") fail("store_version_id_required", "append requires a VersionID", "version_id");
-  parseStableRef(stable_ref);
-  parseVersionId({ version_id, stable_ref, payload: record });
-  return { stable_ref, version_id };
-}
-
-function cloneRecord(value) {
-  if (!value || typeof value !== "object" || Array.isArray(value)) fail("store_record_invalid", "append requires an object record");
-  try { canonicalize(value); } catch (error) { fail(error.code ?? "store_record_invalid", error.message); }
-  return cloneAndFreeze(value);
-}
-
-function compare(left, right) {
-  if (left < right) return -1;
-  if (left > right) return 1;
-  return 0;
-}
-
-/** Create an append-only in-memory store exposing only frozen copies. */
-export function createImmutableStore(input = {}) {
-  const byVersion = new Map();
-  const byStableRef = new Map();
-  const initial = input.entries ?? input.records ?? [];
-  if (!Array.isArray(initial)) fail("store_entries_required", "store entries must be an array", "entries");
-
-  const append = (candidate) => {
-    const value = !candidate?.stable_ref && !candidate?.stableRef
-      ? (candidate?.object ?? candidate?.record ?? candidate?.value ?? candidate)
-      : candidate;
-    const { stable_ref, version_id } = recordRef(value);
-    const frozen = cloneRecord(value);
-    const existing = byVersion.get(version_id);
-    if (existing) {
-      if (canonicalize(existing) !== canonicalize(frozen)) fail("store_version_conflict", "VersionID is already bound to different immutable bytes", "version_id");
-      return existing;
-    }
-    byVersion.set(version_id, frozen);
-    const versions = byStableRef.get(stable_ref) ?? [];
-    byStableRef.set(stable_ref, [...versions, frozen]);
-    return frozen;
-  };
-
-  for (const entry of initial) append(entry);
-
-  const entries = () => [...byVersion.values()].sort((left, right) => compare(left.stable_ref ?? left.stableRef, right.stable_ref ?? right.stableRef) || compare(left.version_id ?? left.versionId, right.version_id ?? right.versionId));
-  const resolve = (reference) => {
-    const value = typeof reference === "string" ? reference : reference?.stable_ref ?? reference?.stableRef ?? reference?.version_id ?? reference?.versionId;
-    if (typeof value !== "string") fail("store_reference_required", "resolve requires a StableRef or VersionID");
-    if (value.includes("@sha256:")) {
-      parseVersionId(value);
-      return byVersion.get(value);
-    }
-    try { parseStableRef(value); } catch (error) { fail(error.code ?? "store_reference_invalid", error.message); }
-    const versions = byStableRef.get(value) ?? [];
-    return versions.length === 0 ? undefined : versions[versions.length - 1];
-  };
-
-  const snapshot = () => deepFreeze({ entries: entries(), size: byVersion.size });
-  return deepFreeze({
-    append,
-    get: resolve,
-    resolve,
-    has: (reference) => resolve(reference) !== undefined,
-    entries: snapshot,
-    listEntries: snapshot,
-    all: snapshot,
-    snapshot,
-    get size() { return byVersion.size; },
-  });
-}
-
-export const createStore = createImmutableStore;
-
-export function appendImmutable(input) {
-  if (!input || typeof input !== "object") fail("store_input_required", "appendImmutable requires {store, record}");
-  const store = input.store ?? input.target;
-  const record = input.record ?? input.object ?? input.value;
-  if (!store || typeof store.append !== "function") fail("store_required", "appendImmutable requires an immutable store", "store");
-  return store.append(record);
-}
-
-export const appendObject = appendImmutable;

package/scripts/artifact-metadata.mjs

@@ -1,20 +0,0 @@
-import crypto from "node:crypto";
-
-const pngSignature = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
-
-function pngDimensions(bytes) {
-  if (bytes.length < 24 || !bytes.subarray(0, 8).equals(pngSignature) || bytes.toString("ascii", 12, 16) !== "IHDR") return undefined;
-  const width = bytes.readUInt32BE(16);
-  const height = bytes.readUInt32BE(20);
-  return width > 0 && height > 0 ? { height, width } : undefined;
-}
-
-export function artifactMetadata(bytes, mediaType) {
-  const metadata = {
-    byte_length: bytes.length,
-    media_type: mediaType,
-    sha256: `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`,
-  };
-  if (mediaType === "image/png") Object.assign(metadata, pngDimensions(bytes));
-  return metadata;
-}