Technical specification

Table of Contents

1. Document Control and Authority
2. Product Definition and Positioning
3. Goals, Non-Goals, and Success Criteria
4. Glossary and Normative Language
5. Scope and Capability Status
6. Constraints and Assumptions
7. Functional Requirements
8. Quality Attributes and Budgets
9. Required Technology Stack
10. System Architecture
11. Domain Model and State Ownership
12. Document Sources and Platform Hosts
13. File Identification, Format Detection, and Text Decoding
14. File Lifecycle and Data Integrity
15. Tabs, Windows, Sessions, and Recovery
16. Renderer System
17. Markdown Viewing and Editing
18. Text and Source Viewing and Editing
19. Image Viewing and Inspection
20. PDF Viewing and Navigation
21. Office Open XML and OpenDocument Viewing
22. Metadata and EXIF Inspector
23. User Interface, Interaction, and Accessibility
24. Platform Strategy
25. Security and Privacy
26. Performance and Large-File Strategy
27. Configuration, Persistence, and Diagnostics
28. Repository Layout and Dependency Governance
29. Contributors and Development Environment
30. Build, Continuous Integration, and Documentation
31. Testing Strategy
32. Packaging, Distribution, and Updates
33. Release and Versioning Process
34. Brand System and Required Brand Kit
35. Spec Kit Decomposition and Decision Records
36. Roadmap Beyond v0.0.0
37. Open Questions
38. Appendices

1. Document Control and Authority

This document is the architecture, behavior, platform, security, development, and delivery contract for the latest official Glitchpad release. Its version MUST equal the product version. v0.0.0 establishes the normative foundation and makes no claim that installable application artifacts exist.

The root Rust workspace version becomes the canonical product-version authority when the repository-foundation slice creates application manifests. Tauri configuration, npm package metadata, Android version name, this document, changelog release heading, release tag, artifact filenames, SBOM metadata, and provenance attestations MUST mirror that value. Automated consistency checks MUST reject any mismatch.

Unreleased changes belong in numbered Spec Kit feature directories under specs/. A completed feature does not alter the latest-release architecture of record until a release documentation pass reconciles it into this document. The pass MUST review every completed slice since the prior release, update affected architecture and behavior, revise capability and platform matrices, update contributor prerequisites and security posture, assemble changelog fragments, regenerate notices, and produce a reviewed documentation-pass receipt before the release tag is created.

flowchart TB
  change["Product decision or behavior change"] --> feature["Spec Kit feature specification"]
  feature --> design["Clarification, plan, contracts, and tasks"]
  design --> implementation["Implementation and mapped verification"]
  implementation --> docsPass["Release documentation pass"]
  docsPass --> consistency{"Versions, behavior, claims, and notices agree?"}
  consistency -->|No| blocked["Release blocked"]
  consistency -->|Yes| release["Official vX.Y.Z release"]

Revision history

Changes to normative released behavior require a product release and a matching specification version. Typographical corrections that do not alter meaning may be applied to the current version with a dated revision-history note and reviewed pull request.

2. Product Definition and Positioning

Glitchpad is a zero-cost, local-first application for opening, reading, inspecting, and selectively editing files. The document owns the viewport. The application supplies only the compact controls needed to interact with the active file and avoids turning file viewing into project, workspace, account, or service management.

The primary jobs are reading rendered Markdown, viewing and editing Mermaid diagrams, editing Markdown and plain text in place, viewing syntax-highlighted source without IDE behavior, opening several related files in compact tabs, checking file and embedded metadata without leaving the application, and viewing images, PDFs, DOCX documents, and ODT documents as their capability gates mature.

Public descriptions MUST follow the released capability matrix. “Everything viewer” is a product direction, not permission to claim unsupported formats.

3. Goals, Non-Goals, and Success Criteria

Goals

• Open an explicitly selected file and display useful content with minimal delay and chrome.
• Preserve editable text encoding, byte-order-mark intent, newline structure, and external revisions without silent data loss.
• Support up to 32 open documents through compact tabs while keeping one active document visually dominant.
• Expose available host, provider, embedded, derived, and renderer-specific metadata through a dismissible inspector.
• Provide one shared behavior contract across Windows, macOS, Linux, and Android, including provider-backed Android documents.
• Keep core viewing, editing, inspection, recovery, and diagnostics offline and account-free.
• Add format families through isolated renderer contracts, hostile-file limits, conformance tests, and truthful release gates.
• Support standalone and Markdown-embedded Mermaid diagrams without rewriting authored layout or requiring an online renderer.
• Produce signed, checksummed, licensed, testable artifacts at a zero-dollar application price.

Non-goals

• Workspaces, project trees, project indexing, project restore, or repository management.
• Language servers, compilation, debugging, terminals, refactoring, package management, or IDE extension systems.
• Browser extensions, browser-hosted file uploads, cloud conversion, accounts, synchronization, collaboration, or telemetry-dependent operation.
• A public plugin marketplace or third-party native-code loading surface.
• Rich document authoring, PDF editing, office-format editing, format conversion, or layout-publishing tools.
• Automatic loading of remote images, fonts, scripts, styles, documents, or office references.
• Electron or a bundled Chromium runtime.

Product success criteria

• v0.1.0 ships official Windows, macOS, Linux, and Android artifacts with Markdown, Mermaid, and text/source view/edit, tabs, metadata inspection, save conflict protection, and crash recovery.
• Every official support claim has automated evidence or an explicit, repeatable manual verification record.
• No save path silently overwrites a conflicting external revision or discards dirty editor state.
• A user can open a file, switch among tabs, inspect metadata, search, edit supported text, and save using keyboard alone on desktop and touch alone on Android.
• Core operation produces no file-content network request and requires no sign-in.

4. Glossary and Normative Language

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY are interpreted as requirement levels consistent with RFC 2119 and RFC 8174 when capitalized.

Notes and rationale are non-normative. Tables labeled as matrices are normative unless their heading states “informative.” Roadmap version targets are commitments subject to the same feature and release gates as any other behavior; they are not current support claims.

5. Scope and Capability Status

v0.0.0 contains no application artifacts. Every application capability is therefore foundation or planned. A capability becomes experimental or stable only through a release that includes the renderer, platform artifacts, conformance evidence, file associations, documentation, and notices.

File dialogs, Android intent filters, desktop file associations, website copy, README claims, and release notes MUST be generated from or checked against the released matrix. Planned rows MUST NOT appear as supported associations.

6. Constraints and Assumptions

Hard constraints

• Tauri 2 is the application and packaging framework. Electron is prohibited.
• Rust owns privileged native operations and untrusted-byte services. TypeScript owns the shared interface and renderer presentation. Kotlin is limited to Android platform integration.
• The application core works offline, without an account, remote service, or telemetry dependency.
• Windows, macOS, Linux, and Android are foundational targets and release-blocking for v0.1.0.
• Markdown prose uses one physical line per paragraph. Project text files use UTF-8 without BOM.
• Normative project diagrams use Mermaid. Project flowcharts and explicit project subgraph directions use top-to-bottom layout; this documentation convention MUST NOT rewrite, reject, or warn about a valid direction authored in an opened user file.
• Original project source and distributable original assets use Apache-2.0.

Validated platform premises

• Tauri 2 supports desktop packaging and Android APK/AAB generation with a minimum Android API level of 24.
• System WebViews differ by platform; renderer conformance and package smoke tests are required on every target family.
• Android document providers may omit stable paths, seek, timestamps, persistent grants, or write support; source capabilities preserve those absences.
• Semantic DOCX and ODT rendering is a deliberate fidelity contract. Page-perfect office layout is outside scope.
• Release signing requires operator-owned platform credentials. Their absence blocks official publication but does not block unsigned development builds.

If a premise becomes false, implementation MUST stop at the affected gate and open a Spec Kit architecture-amendment slice. Implementations MUST NOT conceal the failure through platform-specific behavior that violates the shared contract.

7. Functional Requirements

• TS-FR-001: The application MUST open sources from desktop dialogs, drag-and-drop, command-line or association delivery, and Android view, open-document, create-document, and share intents where applicable.
• TS-FR-002: Opening a source with an identity equal to an existing session MUST focus the existing tab; uncertain identities MUST remain separate.
• TS-FR-003: The active document MUST receive at least 90 percent of the application client area at the 1280 by 800 desktop reference viewport when contextual drawers are closed.
• TS-FR-004: Tabs MUST remain compact, show name and dirty state, support reorder and keyboard switching, and provide bounded overflow without adding a workspace surface.
• TS-FR-005: The metadata inspector MUST be dismissible, preserve document context, and distinguish unavailable, unsupported, redacted, pending, and errored facts.
• TS-FR-006: Format detection MUST use bounded content evidence and MUST NOT trust an extension or externally claimed MIME type as sole authority.
• TS-FR-007: Editable text MUST preserve the accepted encoding, BOM, newline pattern, terminal newline, and undecodable-byte decision.
• TS-FR-008: Save MUST revalidate the external revision and MUST reject a stale write as a conflict.
• TS-FR-009: Close, reload, source revocation, deletion, rename, and abnormal termination MUST preserve dirty content until the user explicitly saves, discards, or declines recovery.
• TS-FR-010: Renderer controls MUST be derived from the active renderer's advertised capabilities.
• TS-FR-011: Every renderer MUST support cancellation, deterministic disposal, malformed-input reporting, resource-limit reporting, and metadata provenance.
• TS-FR-012: Markdown MUST render locally, sanitize generated output, disable raw HTML, and prevent remote resource loading.
• TS-FR-013: Text/source editing MUST provide line numbers, undo/redo, find and replace, go-to-line, wrapping, indentation, encoding/newline visibility, and lazy syntax highlighting without IDE services.
• TS-FR-014: Image viewing MUST support bounded zoom and pan; animated formats MUST expose pause and frame state; ICO MUST expose every embedded image entry.
• TS-FR-015: PDF viewing MUST provide virtualized pages, text search, thumbnails, document outline navigation, page labels, zoom, rotation, internal links, printing, and metadata without executing PDF JavaScript.
• TS-FR-016: DOCX and ODT viewing MUST report unsupported constructs and MUST NOT execute macros, formulas, scripts, or external references.
• TS-FR-017: External links MUST open through the operating system only after scheme validation and explicit user action.
• TS-FR-018: The application MUST remain functional without network access and MUST issue no implicit document-content request.
• TS-FR-019: Crash recovery MUST snapshot dirty editable text, enforce private-storage quotas, expire records after seven days, and remove records after confirmed save or discard.
• TS-FR-020: A malformed, encrypted, oversized, inaccessible, unsupported, or revoked source MUST produce a stable user-visible result without crashing the process.
• TS-FR-021: Every official artifact MUST contain license and notice material, expose the exact product version, and pass install/open/core-action/uninstall smoke tests.
• TS-FR-022: Every product change MUST include a documentation-impact declaration and follow the repository-installed Spec Kit workflow.
• TS-FR-023: Mermaid MUST support standalone .mmd and .mermaid documents plus fenced Markdown blocks through one local renderer contract; standalone source MUST be editable and conflict-safe, each embedded block MUST fail independently, authored source and direction MUST remain unchanged, and scripts, callbacks, automatic links, remote resources, and document-content network requests MUST remain disabled.

8. Quality Attributes and Budgets

Budgets are measured on release builds with fixtures stored in the repository corpus. CI records hardware class, operating system, WebView version, cold or warm state, fixture digest, sample count, median, p95, and peak memory. A release fails a hard limit; two consecutive warning-limit regressions require a performance slice.

Package-size hard limits may change only through a dated decision that identifies the dependency or artifact responsible and measures user value against download and storage impact.

9. Required Technology Stack

Language and framework decision

Rust 1.96.0 with edition 2024 is the native and domain language. It owns source handles, raw-byte access, format evidence, metadata normalization, text round-trip profiles, revision checks, durable persistence, recovery storage, parser limits, and Tauri commands. Rust is selected for memory safety, explicit error handling, predictable native packaging, cross-platform libraries, and the ability to place hostile-file operations outside the WebView.

TypeScript 6 is the shared interface and renderer language. React 19 provides component composition, and Vite 8 provides the development and production bundle. TypeScript is selected because CodeMirror, unified, Mermaid, PDF.js, accessible DOM rendering, and Web Workers provide a mature document ecosystem across every Tauri WebView. React is restricted to view composition; explicit services and reducers own document state so renderer behavior remains testable without a component tree.

Kotlin is limited to the Tauri Android mobile-plugin boundary for intents, ContentResolver, URI grants, descriptors, provider metadata, and lifecycle callbacks. Business rules and renderer behavior MUST NOT be duplicated in Kotlin.

Selected dependency families

An exact dependency enters the repository only after license, provenance, maintenance, vulnerability, bundle, platform, and fixture-corpus review. Patch versions are authoritative in lockfiles, not this prose.

Rejected stack directions

Electron is prohibited. Flutter and Compose Multiplatform replace mature browser renderer dependencies with a larger FFI or reimplementation burden. A fully native Rust UI lacks the required Android and renderer maturity. Per-platform native applications would duplicate behavior and conformance work. A browser-only application cannot implement associations, durable native sources, Android provider semantics, packaging, or offline local authority.

10. System Architecture

Glitchpad uses ports and adapters. The shared shell and renderer registry depend on value contracts. Rust document services implement native source, detection, metadata, save, and recovery ports. Desktop and Android adapters implement platform acquisition and persistence. Renderers cannot import host adapters or invoke arbitrary Tauri APIs.

flowchart TB
  desktop["Desktop acquisition adapters"] --> host["Tauri host and scoped commands"]
  android["Kotlin Android document bridge"] --> host
  host --> core["Rust document core"]
  core --> source["Source handles and revisions"]
  core --> detection["Detection and text profiles"]
  core --> metadata["Metadata normalization"]
  core --> persistence["Save and recovery"]
  source --> session["TypeScript session service"]
  detection --> session
  metadata --> session
  persistence --> session
  session --> shell["React shell and compact tabs"]
  session --> registry["Renderer registry"]
  registry --> markdown["Markdown renderer"]
  registry --> text["Text and source renderer"]
  registry --> image["Image renderer"]
  registry --> pdf["PDF renderer"]
  registry --> office["DOCX and ODT renderers"]

Dependency rules

• glitchpad-core MUST NOT depend on Tauri, React, WebView, or platform UI packages.
• Renderer modules MAY depend on shared TypeScript contracts and renderer-specific workers; they MUST NOT depend on Tauri invocation or native plugin packages.
• The host MAY depend on glitchpad-core and Tauri plugins approved through capability files.
• Android Kotlin code MUST expose the same source operations and error classes as desktop adapters.
• The shell MUST obtain commands from renderer capabilities and MUST NOT branch on file extensions.
• Renderer modularity is internal architecture and does not create a public plugin contract.

Open flow

flowchart TB
  request["Dialog, drop, association, command line, or Android intent"] --> acquire["Host acquires scoped source handle"]
  acquire --> identity{"Existing stable identity?"}
  identity -->|Yes| focus["Focus existing tab"]
  identity -->|No| evidence["Read bounded identification evidence"]
  evidence --> detect["Detect format and text profile"]
  detect --> select{"Safe renderer registered?"}
  select -->|No| unsupported["Show unsupported or malformed result"]
  select -->|Yes| open["Open renderer with bounded byte provider"]
  open --> content["Publish first content and capabilities"]
  content --> enrich["Continue metadata and navigation work asynchronously"]

11. Domain Model and State Ownership

The canonical data contract is specified in specs/002-v000-technical-specification/data-model.md. The core entities are DocumentSource, DocumentIdentity, SourceCapabilities, ExternalRevision, FormatDescriptor, DocumentSession, RendererDescriptor, RendererCapabilities, TextRoundTripProfile, MetadataFact, and RecoveryRecord.

Native source handles are opaque UUID-keyed tokens scoped to one process and session. Desktop identity uses platform file identity with normalized path fallback. Android identity uses provider authority, document ID when available, and canonical URI. A path or URI string alone is never assumed to be stable identity.

Rust owns source handles, external revisions, format evidence, text profiles, normalized metadata, save preconditions, and persisted recovery. TypeScript owns the active editor state, tab order, selections, navigation, visible warnings, and renderer lifecycle. Every editable change increments a session revision. Every save includes the expected session and external revisions.

stateDiagram-v2
  direction TB
  [*] --> Acquiring
  Acquiring --> Detecting
  Detecting --> Loading
  Detecting --> Unsupported
  Loading --> Clean
  Loading --> Failed
  Clean --> Dirty: edit
  Clean --> Reloading: external change
  Dirty --> Saving: save
  Dirty --> Conflicted: external change
  Saving --> Clean: durable receipt
  Saving --> Dirty: write failure
  Saving --> Conflicted: stale revision
  Conflicted --> Dirty: keep local
  Conflicted --> Reloading: use external
  Reloading --> Clean
  Dirty --> RecoveryAvailable: abnormal termination
  RecoveryAvailable --> Dirty: restore
  Clean --> Closed
  Dirty --> Closed: explicit discard
  Unsupported --> Closed
  Failed --> Closed
  Closed --> [*]

12. Document Sources and Platform Hosts

The host contract is specs/002-v000-technical-specification/contracts/document-host.md. A source independently advertises read, seek, stream, stat, watch, revalidate, write, atomic-replace, persistent-permission, rename, and deletion-observation capabilities. An unavailable capability is a normal value and MUST NOT be fabricated.

Desktop adapters accept dialog choices, dropped files, command-line arguments, and operating-system association events. They resolve a platform file identity, open the least-privileged handle needed for advertised operations, and register filesystem watching only while a session needs it.

Android adapters accept system-delivered ACTION_VIEW, ACTION_OPEN_DOCUMENT, ACTION_CREATE_DOCUMENT, and ACTION_SEND intents. The Kotlin bridge uses ContentResolver for descriptors, streams, provider metadata, and persistable grants. It MUST NOT derive or require a desktop-style path. Temporary grants remain temporary; persistent grants are requested only when the intent and provider permit them.

The WebView receives source summaries and opaque IDs. It never receives a reusable native path, content URI grant, unrestricted filesystem scope, or generic read/write command.

13. File Identification, Format Detection, and Text Decoding

Detection evaluates bounded evidence in this order: container or magic signature, trusted parser probe, BOM, encoding validity, filename and extension, MIME hint, shebang, modeline, and content heuristic. Signature and successful parser evidence outrank extension and MIME claims. Every result preserves confidence, evidence, conflicts, and any user override.

flowchart TB
  bytes["Bounded source bytes"] --> signature{"Known signature or container?"}
  signature -->|Yes| probe["Run bounded parser probe"]
  signature -->|No| bom["Check BOM and text validity"]
  probe --> evidence["Record high-confidence evidence"]
  bom --> hints["Evaluate filename, MIME, shebang, modeline, and content hints"]
  hints --> evidence
  evidence --> conflict{"Evidence conflicts or budget exhausted?"}
  conflict -->|Yes| safe["Choose safe fallback and show warning"]
  conflict -->|No| renderer["Select registered renderer"]
  renderer --> override["Allow explicit session override"]

Detection reads at most 256 KiB before renderer selection, spends at most 100 ms desktop or 200 ms Android on synchronous evidence, and runs expensive probes in a worker with a 2-second hard timeout. Archive and PDF probes read only structural ranges when seek is available.

.mmd and .mermaid are Mermaid candidate evidence, not authority. A standalone Mermaid result requires a valid text profile plus a bounded supported diagram declaration or valid Mermaid frontmatter followed by a declaration. Ambiguous text opens through the highest-confidence safe renderer and retains an explicit session override.

Text decoding supports UTF-8, UTF-16LE, UTF-16BE, and a reviewed set of legacy encodings through a dedicated decoding library. UTF-8 without BOM is the default only when bytes validate. Invalid-byte replacement marks the profile as not round-trip safe and disables ordinary save until the user selects an encoding or explicitly accepts a lossy save. BOM presence, newline kind per line, and terminal-newline state are preserved. A user normalization command is the only operation that rewrites mixed newline structure.

14. File Lifecycle and Data Integrity

Opening creates a source handle, observes an external revision, detects the format, selects a renderer, publishes first content, and continues non-critical metadata work asynchronously. Closing disposes the renderer, cancels work, releases object URLs and workers, closes native handles, and removes recovery only after dirty-state resolution.

Desktop save writes a sibling temporary file, flushes content, preserves required permissions, atomically replaces the destination, and syncs the parent directory where the platform provides that primitive. If a platform or filesystem cannot atomically replace, Glitchpad MUST disclose the weaker guarantee before writing and retain a recoverable backup until the replacement succeeds.

Android save writes through a provider descriptor only when the source advertises safe write behavior. A read-only or unsafe provider source uses Save As through ACTION_CREATE_DOCUMENT. The application never truncates a provider source before a complete save payload and revision check are ready.

Before every save, Rust revalidates the external revision. A mismatch moves the session to conflicted, preserves local edits, and offers: compare available metadata, reload and discard local edits, keep local edits and Save As, or explicitly overwrite after a second confirmation. No default action overwrites either revision.

Rename, deletion, watcher overflow, permission revocation, provider unavailability, storage exhaustion, and partial I/O use stable error categories and preserve dirty content. Save success is recognized only from a durable host receipt carrying the new external revision.

15. Tabs, Windows, Sessions, and Recovery

Desktop uses one application window with one compact tab strip. Android uses one activity; phones show the active title and a tab-count switcher that opens a sheet, while tablets may show the desktop-style strip. v0.1.0 does not support multiple application windows.

Tabs have a 32-pixel desktop height, 96-pixel minimum width, 180-pixel preferred maximum width, filename, dirty indicator, close action, accessible full-location tooltip, and drag reorder. Overflow moves excess tabs into a searchable list without creating persistent navigation. The ordinary limit is 32 sessions; opening the thirty-third requires closing a tab or explicitly increasing the safety limit in a future specification.

Ctrl+Tab and Ctrl+Shift+Tab cycle tabs; platform-standard close and save shortcuts act on the active tab. A second desktop invocation forwards open requests to the running process and focuses or creates tabs. Android intents delivered to a running activity follow the same identity rule.

Routine session restoration is disabled. A launch with an explicit source opens that source only. A launch without a source shows a minimal open/drop surface. Crash recovery is enabled for dirty text sessions and is separate from session restore.

Recovery snapshots use application-private storage, owner-only permissions where supported, atomic writes, a seven-day lifetime, and total quotas of 256 MiB desktop and 128 MiB Android. Snapshots are written after 2 seconds of edit idle time and at least every 30 seconds while dirty. If quota pressure threatens the active document, the application warns immediately. Confirmed save or explicit discard removes the matching record.

16. Renderer System

The base renderer contract is specs/002-v000-technical-specification/contracts/renderer.md; Mermaid specializes it through specs/003-mermaid-view-edit/contracts/mermaid-renderer.md. A renderer registers a stable ID, exact format families and variants, maturity, platform set, operations, limits, worker policy, and lazy module loader. Registration order never decides detection priority.

The open context contains a bounded byte provider, cancellation signal, metadata sink, renderer-scoped asset URL factory, theme and accessibility preferences, and progress sink. It contains no arbitrary Tauri invocation, filesystem API, Android URI, network client, or shell executor.

The shell renders only commands advertised by the active renderer. edit, save, and save_as remain independent. A recovered text buffer can be editable while its original source is unavailable, exposing Save As without Save.

CPU-intensive parsing runs in Web Workers or Rust worker threads. Cancellation MUST stop new work within 250 ms. Background tabs suspend decoded image surfaces, PDF canvases, office trees, object URLs, and other regenerable caches. Disposal is idempotent and releases every worker, lease, observer, subscription, and timer.

Every renderer passes the shared conformance suite for first content, capabilities, cancellation, malformed and oversized input, metadata provenance, suspension, repeated open/close, disposal, and platform parity. Editable renderers also pass undo/redo, dirty state, round-trip preservation, conflict, save, Save As, recovery, and lossy-save denial.

17. Markdown Viewing and Editing

Markdown uses one CommonMark-based unified pipeline with GFM tables, task lists, strikethrough, autolinks, and footnotes. Raw HTML is parsed as inert text and never inserted into the document DOM. Generated HTML is sanitized after the final transform through a versioned allowlist.

Rendered view is the default. Source view is the editing surface. A compact mode action toggles between rendered and source views; split view is deferred until a measured workflow demonstrates that its permanent viewport cost is justified. Preview updates are debounced at 100 ms and cancel superseded work.

Local relative images resolve through renderer-scoped asset tokens only after path normalization and source-root checks. Remote images, fonts, styles, embeds, and includes remain blocked. External links display the destination host and open through the operating system after scheme validation and explicit action. file:, javascript:, data: navigation, custom executable schemes, and embedded frames are blocked.

Fenced code receives escaped syntax highlighting from lazy language packages. Fenced mermaid content renders through the shared Mermaid adapter with strict immutable security configuration, no click callbacks, no native authority, no remote resources, and a final SVG allowlist after generation. Each block has a revision-bound result and bounded fallback so malformed or over-limit source cannot prevent the surrounding Markdown or another block from rendering. Authored direction is preserved.

Markdown editing provides undo/redo, line numbers, find/replace, go-to-line, wrapping, indentation, bracket handling, and round-trip encoding/newline behavior. The renderer does not provide format conversion, selectable parser engines, HTML authoring, or project-wide link validation.

Mermaid diagram documents

Mermaid is a text-based diagram language commonly embedded in Markdown, not a Markdown subset. Standalone .mmd and .mermaid files use the editable-text lifecycle and open in rendered mode when valid. A compact action switches between rendered and source modes; empty, currently unrenderable, or over-limit source opens in source mode when no prior valid preview exists.

Source mode provides the same encoding/newline preservation, undo/redo, find/replace, line navigation, dirty state, recovery, conflict detection, Save, and Save As behavior as editable text. Rendering never serializes, formats, repairs, or rewrites the source. Diagram type, comments, whitespace, safe directives, and layout direction remain authored content. The project's top-to-bottom documentation convention has no effect on opened user documents.

Preview validation begins 300 ms after the newest source edit. Requests are keyed to the exact source revision; superseded, cancelled, hidden, or stale results cannot replace current output. A parse or render failure preserves all source and keeps the last valid preview visibly marked as stale when one exists. Diagnostics classify malformed source, unsupported syntax, resource limits, cancellation, and internal failure, with line and column only when parser evidence is reliable.

Rendered mode provides fit-to-view, actual size, zoom from 10 to 800 percent, reset, bounded pan, rendered-label search, copy, and metadata inspection through compact contextual controls. Keyboard, pointer, and touch paths remain equivalent. Authored accTitle and accDescr label the sanitized SVG; unannotated diagrams receive a localized filename/type or block-position label plus a direct route to source.

Mermaid does not provide generated SVG/PNG/PDF export, presentation mode, visual graph manipulation, online rendering, collaboration, callbacks, user renderer plugins, or automatic layout conversion.

18. Text and Source Viewing and Editing

The text renderer provides a lightweight editor, not an IDE. It includes line numbers, selectable wrapping, find and replace, go-to-line, undo/redo, multi-selection supplied by CodeMirror, indentation commands, encoding and newline status, syntax highlighting, and explicit language override.

Language detection uses exact filename, extension, shebang, modeline, and bounded content evidence. CodeMirror language packages load only when selected. Unknown text opens as plain text. A user override affects the session; persistent extension overrides require an explicit preference action.

Mermaid source mode is a specialized text language mode. It adds diagram diagnostics and preview navigation but MUST NOT acquire language-server, execution, workspace, or visual-source-generation behavior.

The renderer MUST NOT implement language servers, compilers, build commands, debugging, terminals, project search, project symbols, package management, repository operations, AI completion, or IDE refactoring.

Files through 32 MiB support full editing and syntax highlighting subject to line limits. Files from 32 MiB through 256 MiB open in virtualized large-text read-only mode with search and copy; syntax highlighting is disabled. Files above 256 MiB are refused with size and alternative-tool guidance. A single line above 2 MiB disables syntax parsing for that document and remains viewable in plain-text mode.

19. Image Viewing and Inspection

Image support activates in v0.2.0. Required raster formats are PNG, JPEG, GIF, WebP, BMP, and TIFF. SVG and ICO are separate variants under the image renderer family.

The renderer provides fit, actual-size, zoom, pan, background selection for transparency, orientation handling, pixel dimensions, animation pause/resume, frame position, and metadata inspection. It does not modify image pixels or write image containers.

Rust identifies and validates containers before presentation. The image crate uses explicit codec features. WebView decoding may provide a display fast path only after native size and format checks. A separate libwebp dependency is not part of the baseline because pure-Rust and system decoders satisfy required WebP behavior without a C packaging surface.

ICO inspection lists each directory entry with width, height, bit depth, encoding, byte size, and validity. The user may preview and export one embedded entry as PNG without altering the source.

SVG is parsed by usvg and rendered by resvg. Scripts, event handlers, foreign objects, external styles, fonts, images, links, and network references are discarded or reported. Untrusted SVG is never inserted directly into the application DOM.

20. PDF Viewing and Navigation

PDF support activates in v0.3.0 and uses the PDF.js display layer in a dedicated worker. Glitchpad supplies its own compact shell rather than embedding the generic PDF.js viewer.

The renderer provides virtualized page canvases, text selection, search, thumbnails, document outline and table-of-contents navigation, page labels, direct page navigation, zoom, rotation, internal links, metadata, and printing. Only visible and adjacent pages remain rendered; suspended tabs release canvases and retain compact navigation state.

PDF JavaScript, form submission, embedded-file launch, multimedia, remote resource access, automatic external-link opening, annotations editing, signatures, redaction, and document modification are disabled. Encrypted documents may request a password for in-memory use; passwords are never persisted or logged. Unsupported encryption produces a stable error.

The renderer accepts files through 512 MiB desktop and 256 MiB Android, at most 10,000 pages, and at most 200 MiB of active rendered surfaces desktop or 96 MiB Android. Ranged reads are used when the source supports seek. First content is the first requested page, not complete document parsing.

21. Office Open XML and OpenDocument Viewing

DOCX support activates in v0.4.0. Mammoth converts Word semantics to a renderer-neutral HTML tree, which passes through the shared sanitizer. Supported content includes headings, paragraphs, lists, tables, hyperlinks, footnotes/endnotes, inline images, basic emphasis, and core document properties. The renderer provides heading navigation, search, copy, and metadata.

ODT support activates in v0.5.0. A bounded Rust parser reads the OASIS OpenDocument 1.4 package structure with zip and quick-xml, validates required package entries, and emits the same semantic document tree used by the office presentation layer. Supported content includes headings, paragraphs, lists, tables, hyperlinks, notes, inline images, basic text styles, and document metadata.

The fidelity promise for both formats is semantic readability. Pagination, exact font substitution, line wrapping, floating-object placement, tracked changes, comments workflows, fields, formulas, charts, macros, scripts, embedded executables, external resources, and editing are not promised. Unsupported constructs produce a per-document report rather than disappearing silently.

Office containers are limited to 128 MiB compressed input, 10,000 entries, 512 MiB expanded desktop or 256 MiB Android, 100:1 aggregate expansion, 20 nested relationship traversals, and normalized internal paths with traversal rejection. Encrypted packages are reported as unsupported in their first renderer releases.

22. Metadata and EXIF Inspector

The metadata inspector is opened by a compact information icon in the active document bar or the platform menu. Desktop uses a dismissible right-side overlay up to 360 pixels wide. Android uses a bottom sheet on phones and a side sheet on tablets. Closing it restores the full document surface.

Facts are grouped as Source, Content, Embedded, Derived, and Renderer. Every fact includes a typed value, source, availability, unit, sensitivity, and copy policy. The interface shows Not provided, Unsupported, Redacted, Pending, or a stable error instead of inventing a value.

Source facts include display name, source kind, size, observed modification time, creation/birth time when the host supplies it, permissions or provider write state, identity confidence, and current external revision. Text facts include encoding, BOM, newline pattern, line and character counts, language mode, and round-trip safety. Mermaid facts include detected diagram type, parser version and status, current and preview revisions, stale-preview state, authored accessibility annotation presence, source bytes, edge count, output bytes, timings, and active limit result when available. Image facts include dimensions, frames, color model, orientation, EXIF, IPTC, XMP, and ICO entries. PDF and office facts include title, author, subject, keywords, creator, producer, page or structural counts, and format version when parsable.

EXIF GPS facts are collapsed and marked sensitive by default. Copying coordinates requires an explicit action. Checksums are absent until requested; SHA-256 calculation runs cancellably and reports the external revision it represents.

Metadata extraction obeys the same parser and resource limits as rendering. A metadata failure cannot prevent content viewing unless it proves the source is malformed for the selected renderer.

23. User Interface, Interaction, and Accessibility

The file owns the viewport. Permanent UI consists of the platform window frame, one compact document bar, one compact tab surface where space permits, and renderer controls that appear only when the active capability requires them. There is no sidebar, dashboard, project tree, ribbon, status-panel stack, promotional content, or persistent metadata region.

At 1280 by 800 with drawers closed, document content occupies at least 90 percent of client-area pixels. The combined desktop document and tab bars remain at or below 72 pixels. Icons use 16- or 18-pixel artwork inside minimum 32-pixel desktop targets. Android touch targets meet a 48-density-independent-pixel minimum without enlarging the visible icon.

Desktop tabs expose full accessible names, dirty state, close state, and position. Phone layouts expose active title, tab count, open, information, and overflow actions; the tab sheet supports search only when overflow exists. Renderer controls may collapse into overflow before reducing the document below its minimum area.

Keyboard navigation follows platform conventions and maintains a visible focus indicator. Screen readers receive semantic headings, landmarks, tab roles, progress state, error summaries, metadata groups, page counts, and renderer command names. Dynamic updates use restrained live regions and never announce every keystroke or scroll event.

Mermaid rendered/source mode, fit, zoom, reset, pan, search, stale-preview state, diagnostics, and metadata are exposed through renderer-contextual controls. Generated SVG cannot trap sequential focus. Diagram labels remain searchable, authored accessible titles and descriptions are preserved, and every successful unannotated diagram receives a fallback label and source route.

Color meets WCAG 2.2 AA contrast. The application honors system light/dark theme, high-contrast or forced-colors behavior where available, reduced motion, text scaling, and browser zoom. Motion is limited to state continuity and remains below 200 ms; no essential information depends on animation or color alone.

The initial language is US English. All user-visible strings, dates, units, plurals, and shortcuts use localization-ready resources. File names and metadata values are never translated.

24. Platform Strategy

All four target families are Tier 1 for v0.1.0. A Tier 1 platform requires an official artifact, native build host, automated shared suite, adapter tests, installation smoke tests, core user-flow evidence, version and license evidence, and a named support baseline.

Windows file associations and command-line delivery route to the running instance. macOS handles open-document application events. Linux follows freedesktop MIME registration and desktop-entry conventions. Android registers only released format MIME types and extensions and accepts view/open/share intents according to provider grants. .mmd and .mermaid associations and intent filters activate only when the standalone Mermaid capability reaches stable status on the complete Tier 1 matrix.

Windows ARM64 and Linux ARM64 are planned platform expansions after v0.1.0 and require their own build, package, and device evidence. iOS is outside the current platform boundary.

System WebView versions are recorded in diagnostics and test evidence. Glitchpad does not bundle a browser engine to mask obsolete or broken system WebViews; unsupported runtimes receive a precise prerequisite error.

25. Security and Privacy

Every opened source is hostile input. The trust boundary begins at native acquisition and remains in force through detection, parsing, generated markup, metadata, navigation, saving, caching, logs, and packaging.

The Tauri capability set is deny-by-default and scoped by window and command. The application exposes source-handle operations, not generic filesystem or shell plugins. Capability files MUST avoid overlapping grants that silently merge permissions. Development-only capabilities are absent from release bundles.

The release content-security policy uses default-src 'self', denies network connections, objects, arbitrary frames, form submissions, and base changes, and permits only bundled scripts/styles plus scoped blob/data or application-asset sources required by reviewed renderers. The sole framed exception is a bundled, sandboxed Mermaid render context with scripts but no same-origin authority, navigation, opener, forms, downloads, storage, network, or Tauri bridge; its typed message contract contains bounded source and render results only. Inline script and eval are prohibited. Remote images, fonts, styles, workers, and media are prohibited.

Generated Markdown, DOCX, ODT, and Mermaid output is sanitized after the final unsafe transformation. Mermaid's generated SVG passes an application-owned element, attribute, namespace, CSS, URL, and output-size allowlist before insertion; standalone SVG documents remain rasterized or represented through a safe tree and are never inserted as source DOM. PDF JavaScript and office macros never execute. Archive paths are normalized and traversal is rejected. External references are reported and not fetched.

Renderer limits cover source bytes, probe bytes, decoded pixels, pages, canvases, archive entries, expanded bytes, compression ratio, relationship depth, CPU time, memory, and concurrent workers. Timeouts and cancellations produce explicit results. A parser panic or worker termination cannot crash the application host or corrupt a source.

Temporary files and recovery records use application-private directories and owner-only permissions where supported. Sensitive metadata and full locators are redacted from logs. Diagnostic bundles require explicit user creation and preview. No telemetry, crash upload, analytics, or background network report is enabled.

Dependency security uses locked inputs, automated vulnerability and license checks, secret scanning, SBOM generation, provenance attestations, and prompt review of parser advisories. Security reports use the repository security policy and private disclosure channel established by the repository-foundation slice.

26. Performance and Large-File Strategy

Whole-file buffering is permitted only inside the format limits below and only when peak decoded memory remains inside the renderer budget. Seek-capable sources use ranged reads for PDF and bounded probes. Stream-only Android sources may use an application-private cache when a renderer requires seek; the cache obeys source-size, quota, privacy, revision, and cleanup rules.

Work is chunked around the UI event loop. Main-thread tasks SHOULD remain below 16 ms and MUST NOT repeatedly exceed 50 ms during interaction. Syntax, Markdown, Mermaid, PDF, image, checksum, and office work is cancellable. Mermaid allows one current request per owner and two active render contexts application-wide. Switching tabs prioritizes active content and suspends background rendering.

Performance tests use small, medium, boundary, and hostile fixtures with stable digests. A claim is invalid without the fixture, host, WebView, build profile, sample count, and measurement output.

27. Configuration, Persistence, and Diagnostics

The v0.1.0 preference schema contains theme, editor font family and size, line wrapping, tab width, Markdown default mode, and explicit language overrides. It contains no account, synchronization, workspace, telemetry, remote-resource, plugin, or recent-file setting.

Preferences are schema-versioned JSON in the platform application-config directory. Writes are atomic. A migration is deterministic and covered by fixtures; an unreadable future schema is preserved and reported instead of overwritten.

Recovery records and bounded renderer caches live in application-private data/cache directories. Recovery survives abnormal termination and expires after seven days. Regenerable caches are disposable, revision-keyed, quota-bound, and cleared by the user or automatically after expiry. No database is used.

Structured logs include timestamp, level, stable event ID, platform, component, duration, byte count, and stable error code. They exclude content, editor text, passwords, full paths, raw Android URIs, EXIF values, and recovery payloads. Release logs default to information level with bounded rolling retention.

The About/Environment surface shows product version, specification version, platform, architecture, WebView version, Rust core version, renderer versions, capability status, build commit, and license links. An explicit diagnostic export lets the user preview redacted logs and environment facts before saving a local bundle.

28. Repository Layout and Dependency Governance

apps/glitchpad/          Shared TypeScript, React, renderers, workers, and UI tests
crates/glitchpad-core/   Platform-independent document, detection, metadata, and persistence rules
crates/glitchpad-host/   Tauri host, scoped capabilities, desktop adapters, generated Android host
crates/xtask/            Cross-platform doctor, bootstrap, check, test, docs, package, and release gates
docs/                    Technical specification, ADRs, brand, contributor, security, and operations docs
fixtures/                Licensed document corpus, hostile cases, expected outputs, and provenance
specs/                   Spec Kit feature specifications, plans, contracts, tasks, and analysis
scripts/                 Narrow helpers invoked and validated by xtask

Dependency direction is renderer → shared renderer contracts, shell → session and renderer contracts, host → core, adapters → host ports. Core code never imports application UI or Tauri. Renderer code never imports host adapters.

Cargo.lock, pnpm-lock.yaml, and Gradle dependency locks are committed. Rust default features are disabled for parser and codec crates unless every default is reviewed. JavaScript production dependencies are separated from development dependencies. Generated files identify their source and have drift checks.

The automatic license allowlist is Apache-2.0, MIT, BSD-2-Clause, BSD-3-Clause, ISC, Zlib, Unicode-3.0, CC0-1.0, and 0BSD. MPL-2.0, LGPL, fonts, media, standards fixtures, and licenses outside the allowlist require a dated Spec Kit decision and documented obligations. GPL, AGPL, SSPL, Commons Clause, Business Source License, non-commercial, no-derivatives, source-available, custom ambiguous, and unlicensed inputs are prohibited in distributed artifacts.

Every dependency requires package-registry provenance, upstream repository, license evidence, maintenance review, advisory review, bundle impact, platform support, test seam, and removal fallback. Abandoned parsers and renderers are replaced or disabled before their unsupported state becomes a security exposure.

29. Contributors and Development Environment

cargo xtask doctor is the executable environment contract after repository foundation. It validates required versions, components, environment variables, native libraries, WebViews, emulators, disk space, and optional release credentials. Documentation references machine-readable authorities and does not own duplicate patch versions.

Shared required environment

The bootstrap sequence is cargo xtask doctor, cargo xtask bootstrap, and cargo xtask check. Bootstrap installs locked JavaScript dependencies, Rust test tools declared by xtask, Playwright browser binaries, and development fixture indexes. It does not install operating-system packages or release credentials.

Windows host

• Windows 11 x86_64 with current security updates.
• Visual Studio 2022 Build Tools with Desktop development with C++, MSVC toolset, CMake tools, and Windows 11 SDK.
• WebView2 Evergreen Runtime and a matching test runtime where CI pins one.
• Rust target x86_64-pc-windows-msvc.
• NSIS tooling selected by the Tauri lock and Windows signing tools for release operators.

macOS host

• macOS 13 or newer on Apple Silicon or Intel.
• Full Xcode selected by xcode-select, accepted license, command-line tools, and SDK version matching the release runner.
• Rust targets aarch64-apple-darwin and x86_64-apple-darwin for universal artifacts.
• Apple Developer ID Application identity, notarization credentials, and keychain profile for release operators only.

Linux host

• Ubuntu 22.04 x86_64 as the release-build baseline; Ubuntu 24.04 is the current development and compatibility host.
• Build compiler, pkg-config, WebKitGTK 4.1 development files, GTK 3 development files, AppIndicator/Ayatana development files, librsvg development files, OpenSSL development files required by system tooling, patchelf, AppImage tooling, Debian packaging tools, and headless display dependencies.
• Rust target x86_64-unknown-linux-gnu.
• At least one installed font package for deterministic text and renderer tests.

Android host

• Android Studio Quail 3 (2026.1.3) or newer compatible stable release.
• JDK 17 through 21 for the Android build; CI pins Temurin 17 and a compatible Android Studio bundled JBR 21 is valid locally.
• Android SDK Platform 36, Build Tools 36.0.0, current Platform Tools and command-line tools, Android Emulator, and API 24 plus API 36 handset images.
• NDK 28.2.13676358, owned by the Android Gradle configuration.
• ANDROID_HOME, NDK_HOME, and JAVA_HOME set to doctor-verifiable locations.
• Rust targets aarch64-linux-android, armv7-linux-androideabi, i686-linux-android, and x86_64-linux-android installed through rustup.
• adb, hardware virtualization, one API 36 emulator, one physical ARM64 device at API 36, and one physical or hosted device at API 24 for release evidence.
• Android app-signing keystore and Google Play credentials for release operators only.

Test and documentation tools

• Rust: rustfmt, Clippy, cargo-nextest, cargo-deny, cargo-audit, cargo-fuzz, proptest dependencies, and coverage tooling selected in the tool manifest.
• TypeScript: Vitest, Testing Library, Playwright with pinned browser binaries, axe-core, and visual-diff tooling.
• Android: Gradle wrapper, JVM tests, connected instrumentation tests, emulator control, and package smoke tooling.
• Documentation: Prettier with proseWrap: never, markdownlint with MD013 disabled, Mermaid CLI, link checker, spelling/terminology checker, and strict UTF-8/BOM/mojibake validator.
• Supply chain: SPDX/REUSE validation, CycloneDX generation, license notice generation, vulnerability checks, SHA-256 tools, signing clients, and provenance attestation tooling.
• Brand: SVG editor capable of standards-compliant source output, scripted raster/icon exporters, font-license records, and lossless image optimization.

Workstation requirements

Ordinary development requires 16 GiB RAM, 8 logical CPU cores, 40 GiB free disk after toolchains, and hardware virtualization for Android emulator work. Packaging and full local matrix work SHOULD use 32 GiB RAM and 80 GiB free disk. A physical Android release device and platform-specific signing identities are release-only resources.

30. Build, Continuous Integration, and Documentation

cargo xtask is the cross-platform command surface. doctor validates the host, bootstrap installs repository-scoped tools, check runs shared merge gates, test runs selectable test tiers, docs runs documentation gates, package builds development artifacts, and release-check validates release-only state and credentials. CI invokes the same subcommands with locked dependencies.

flowchart TB
  change["Pull request"] --> classify["Classify affected paths"]
  classify --> docs["Documentation and version gates"]
  classify --> shared["Rust and TypeScript shared checks"]
  classify --> security["Security, licenses, and supply chain"]
  shared --> platform["Affected native platform checks"]
  docs --> aggregate{"Required aggregate status"}
  security --> aggregate
  platform --> aggregate
  aggregate -->|Fail| blocked["Merge blocked"]
  aggregate -->|Pass| review["Human review and merge"]

Every pull request runs formatting, Clippy with warnings denied, TypeScript typecheck, JavaScript lint, unit and contract tests, documentation gates, dependency/license checks, secret scan, and an always-reporting aggregate status. Path filtering MAY skip irrelevant heavy platform jobs, but scheduled and release workflows run the complete matrix and the aggregate gate must distinguish skipped from failed jobs.

Documentation gates include Prettier, markdownlint, internal-anchor validation, external-link validation, Mermaid parse and render validation, top-to-bottom direction validation for project-authored documentation diagrams, spelling and terminology, UTF-8 without BOM, mojibake detection, specification/product version equality, capability-claim consistency, and documentation-impact declaration. User-document fixtures MAY contain any valid authored Mermaid direction and MUST be excluded from the project-direction rule while remaining included in parser and renderer conformance.

Release CI performs no unreviewed source rewrite. Documentation reconciliation, changelog assembly, version bumps, and the release receipt are committed and reviewed before tagging. Tag workflows verify, build, test, sign, attest, and publish.

31. Testing Strategy

Fixture provenance is recorded in fixtures/provenance.toml with source, author, license, redistribution permission, format, feature purpose, digest, sensitivity review, and expected result. Production documents and private user data are prohibited as fixtures. Hostile fixtures remain inert outside the parser harness and carry clear warnings.

Size classes are tiny, normal, medium, boundary, over-limit, malformed, truncated, contradictory, encrypted, and adversarial. Golden updates require a reviewed explanation of why output changed. CI retries infrastructure setup, not failing assertions. A flaky test is quarantined only with an owner, issue, expiry, and replacement gate; release-critical tests cannot be quarantined.

Coverage is a diagnostic, not a success metric. Critical state, save, recovery, detection, permission, and parser-limit branches require direct tests regardless of aggregate percentage.

32. Packaging, Distribution, and Updates

Official artifact names follow glitchpad-{version}-{platform}-{arch}.{ext} and contain or accompany LICENSE, NOTICE, THIRD_PARTY_NOTICES, SHA-256 checksums, CycloneDX SBOM, and provenance attestation.

Windows publishes an x86_64 NSIS current-user installer and portable ZIP. macOS publishes one universal signed and notarized DMG. Linux publishes an x86_64 AppImage and Debian package built against the declared glibc baseline. Android publishes a universal APK, a split ARM64 APK for direct installation, and an AAB for Google Play.

Desktop packages register only stable editable/viewable formats from the release matrix. Android intent filters follow the same rule. Uninstall removes application binaries and registered associations while preserving user-created documents; platform conventions decide whether preferences and recovery data remain, and the uninstaller must disclose any removal option.

v0.1.0 has no in-app updater. Direct-distribution users obtain signed releases through the project release channel; store users use platform-store updates. A future updater requires a separate threat model, signed manifest, rollback policy, channel model, proxy/offline behavior, and recovery test matrix.

No artifact is official without its platform signature where signing exists, clean-environment smoke result, checksum, SBOM, provenance, license notices, and exact version evidence.

33. Release and Versioning Process

Glitchpad follows semantic versioning. Before 1.0.0, a minor release may change unstable application behavior, but save integrity, source privacy, license, and release-evidence guarantees remain compatibility commitments. Patch releases contain compatible fixes and documentation corrections. v0.0.0 is the foundation release; v0.1.0 is the first binary release.

Every change reaches the default branch through a reviewed pull request with a green aggregate gate. Changelog entries are contributed as fragments to avoid concurrent edits. The release operator assembles fragments, performs the documentation pass, updates the canonical product version and mirrors, reviews generated notices, commits the release, and pushes vX.Y.Z.

The tag pipeline verifies the release contract in specs/002-v000-technical-specification/contracts/release-gates.md, runs shared gates, builds the four-platform matrix, runs package smoke tests, signs artifacts, generates checksums/SBOM/provenance, creates the release, and performs post-publication download and verification checks.

flowchart TB
  slices["Completed Spec Kit slices"] --> reconcile["Documentation and changelog reconciliation"]
  reconcile --> commit["Reviewed release commit"]
  commit --> tag["Operator pushes vX.Y.Z"]
  tag --> verify["Version, docs, tests, security, and license gates"]
  verify --> builds["Windows, macOS, Linux, and Android builds"]
  builds --> smoke["Install and core-behavior smoke tests"]
  smoke --> supply["Sign, checksum, SBOM, and attest"]
  supply --> publish{"Every required artifact and receipt present?"}
  publish -->|No| blocked["Publication blocked"]
  publish -->|Yes| release["Publish official release"]
  release --> post["Post-release verification"]

A failed platform leg blocks the release. Partial publication is not promoted as official. Post-release failure halts channel promotion and opens a release-remediation slice; published assets remain clearly marked until corrected or withdrawn.

34. Brand System and Required Brand Kit

The Glitchpad brand reinforces a compact, technical, calm, and slightly unconventional product without taking space from the document. Brand expression belongs in the application icon, typography, color, restrained motion, empty state, packaging, and public materials.

The required source kit contains primary symbol, wordmark, horizontal and stacked lockups, light/dark/monochrome variants, clear-space and minimum-size rules, accessible color tokens, typography and fallback stack, icon style, motion rules, naming and voice guidance, misuse examples, and license/provenance records.

Required exports include SVG master assets; Windows ICO with required embedded sizes; macOS ICNS; Linux PNG/SVG sizes; Android adaptive foreground, background, and monochrome layers; launcher and notification icons; repository social preview; release artwork; favicon/web metadata; store listing icon, feature graphic, and screenshots; and print-safe monochrome assets.

Source assets live under brand/ and generated application/store assets live under platform-owned directories. A deterministic export command regenerates outputs and CI checks drift. Color tokens pass WCAG contrast in both themes. Fonts require redistribution and embedding approval recorded with the brand sources.

Brand changes use Spec Kit when they alter product naming, UI tokens, accessibility, packaging, or public assets. A release cannot publish placeholder icons or assets that disagree with the approved kit.

The unreleased S007 repository delta imports approved brand canon 1.0.0 under brand/, uses selected checksum-verified copies in production integrations, and introduces a statically exported Next.js and Fumadocs public site under site/. The repository docs/ tree remains the authored documentation authority, with a generated public adaptation served under /docs. Pull requests and default-branch updates validate the export without publishing it; production deployment, Pages configuration, and glitchpad.com DNS remain explicit owner-controlled operations.

The unreleased S009 operational delta transferred glitchpad.com from the legacy personal GitHub Pages attachment to the shruggietech/glitchpad workflow deployment. Cloudflare remains authoritative DNS with DNS-only website records, GitHub organization verification protects the apex and immediate subdomains through a persistent challenge, glitchpad.com is canonical, www redirects to the apex, and HTTPS is enforced with certificate coverage for both hosts. The migration committed a sanitized baseline, validated the reviewed main deployment on a temporary preview, applied expected-state guards to every provider mutation, preserved unrelated DNS and account configuration, proved production over IPv4 and IPv6, and disabled only the legacy Pages configuration after final validation while retaining its repository recovery source. The durable runbook and final evidence live under docs/operations/. Recovery is phase-specific because organization verification must be removed before an exact post-transfer return to a personal-account Pages attachment.

35. Spec Kit Decomposition and Decision Records

Spec Kit is mandatory for every feature, renderer, platform capability, architecture amendment, security change, dependency-policy change, brand-system change, and release preparation.

The required sequence is specify, clarify when material ambiguity exists, plan and research, tasks, analysis, implementation, convergence, and release reconciliation. No implementation may silently settle an architecture question. A decision records date, status, context, selected option, rationale, alternatives, consequences, affected requirements, and superseding decision.

The architecture of record changes only during a release documentation pass. Feature artifacts remain in the repository as historical intent and evidence; they do not override a later released specification.

36. Roadmap Beyond v0.0.0

Version targets may consolidate when all included exit conditions pass. Dependency order and support-matrix evidence cannot be waived to meet a version date. Every renderer remains absent from associations and public support claims until its activation release.

Later quality slices may add Windows ARM64, Linux ARM64, an opt-in session restore, a signed updater, or deeper metadata formats. Each requires measured user value and a bounded specification.

37. Open Questions

There are no unresolved architecture or product questions in v0.0.0. Implementation discoveries that materially challenge this specification MUST create a Spec Kit clarification or architecture-amendment slice before code selects a different behavior.

Risks with fixed containment and blocking gates are recorded in specs/002-v000-technical-specification/plan.md; they are not permission to choose alternatives silently.

38. Appendices

Appendix A. Capability-state rules

Appendix B. Platform artifact and evidence matrix

Appendix C. Metadata catalog groups

• host.*: source kind, display name, size, observed times, permissions/provider write state, identity confidence, external revision.
• text.*: encoding, BOM, newline pattern, terminal newline, line/character counts, language, round-trip safety.
• diagram.*: diagram type, parser version/status, current and preview revisions, stale-preview state, accessible-title/description presence, source/edge/output measurements, timings, and limit result.
• image.*: dimensions, frames, codec, bit depth, color model, alpha, orientation, animation duration.
• exif.*, iptc.*, xmp.*: embedded fields with exact provenance and sensitivity.
• ico.*: entry count and per-entry dimensions, bit depth, encoding, byte size, validity.
• pdf.*: version, pages, title, author, subject, keywords, creator, producer, dates, outline presence, encryption.
• office.*: package type, title, author, subject, keywords, dates, headings, tables, images, notes, unsupported construct counts.
• derived.*: SHA-256, counts, parser warnings, detection confidence, evidence conflicts.

Appendix D. Interaction matrix

Shortcuts MUST yield to platform-reserved behavior and remain discoverable in command labels. Touch alternatives are required for every essential action.

Appendix E. Version-authority matrix

Appendix F. Fixture classes

• Valid minimal, representative, complex, and boundary documents for each supported format.
• Encoding fixtures for UTF-8, UTF-16, legacy encodings, BOM variants, mixed newlines, terminal newline, and invalid bytes.
• Contradictory extension, MIME, signature, shebang, modeline, and parser evidence.
• Truncated, malformed, encrypted, decompression-bomb, path-traversal, recursive, oversized, high-pixel, high-page, and timeout cases.
• Metadata fixtures with missing, malformed, duplicate, sensitive GPS, timezone, precision, and unsupported values.
• External-change, rename, deletion, permission-revocation, storage-full, partial-write, and recovery-quota scenarios.
• Accessibility and localization fixtures with long names, right-to-left text, combining characters, emoji, and high zoom.
• Mermaid fixtures for every enabled diagram type, .mmd and .mermaid, fenced blocks, authored directions, accessibility annotations, rapid revisions, stale previews, secure-key overrides, active content, remote resources, output expansion, limits, cancellation, and sanitizer bypass attempts.

Appendix G. Packaging inventory

• Windows: NSIS installer, portable ZIP, signature, checksums, SBOM, provenance, notices.
• macOS: universal DMG, application signature, notarization ticket, checksums, SBOM, provenance, notices.
• Linux: AppImage, Debian package, checksums, SBOM, provenance, notices.
• Android: universal APK, split ARM64 APK, AAB, signatures, checksums, SBOM, provenance, notices.
• Release: source archive, release notes, documentation-pass receipt, capability matrix, platform matrix, and verification summary.

Appendix H. Foundation decision index

Appendix I. Mermaid diagram inventory

Appendix J. Primary references

• Apache License 2.0
• Tauri 2 prerequisites
• Tauri distribution
• Tauri Android and Google Play packaging
• Tauri capabilities
• Android target API requirements
• Android 16 SDK setup
• Android SDK version semantics
• Node.js release schedule
• Rust 1.96.0 release
• Vite requirements
• CodeMirror system guide
• Mermaid API usage
• Mermaid security levels
• Mermaid secure configuration
• Mermaid accessibility options
• Mermaid CLI and standalone .mmd files
• rehype-sanitize
• Rust image crate formats
• kamadak-exif
• PDF.js documentation
• Mammoth DOCX semantic conversion
• OpenDocument 1.4
• CommonMark
• GitHub Flavored Markdown
• WCAG 2.2
• RFC 2119
• RFC 8174

Appendix K. Release documentation pass checklist

• Enumerate every completed Spec Kit slice since the prior release and record its disposition.
• Reconcile architecture, behavior, domain model, security, performance, and platform changes into this document.
• Update capability, platform, metadata, interaction, contributor, fixture, packaging, decision, and diagram appendices.
• Verify file associations, Android intent filters, dialog filters, renderer registration, README, release notes, and public claims against the capability matrix.
• Verify toolchain and SDK authorities against contributor documentation and CI images.
• Re-run dependency license, notice, vulnerability, SBOM, provenance, and secret checks.
• Assemble changelog fragments and confirm a non-empty release section.
• Set the canonical product version and every validated mirror, including this specification.
• Produce and review the machine-readable documentation-pass receipt.
• Run cargo xtask release-check before creating the release tag.