@meoslabs/save-in-meos 0.0.1

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 meoslabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Bundled font files under assets/fonts/ are licensed separately under the
+SIL Open Font License 1.1 — see assets/fonts/inconsolata/OFL.txt.

package/README.md

@@ -0,0 +1,171 @@
+# @meoslabs/save-in-meos
+
+**meos deeplink protocol (MDP)** codec and **save in meos** embed widget for third-party sites.
+
+Let visitors save a page (or a quote from it) into [meos](https://meos.do) with one tap. This package builds canonical import URLs and ships a branded, self-contained button you can drop into any site — via npm, a script tag, or programmatic imports only.
+
+## How to integrate
+
+| Use case | How |
+|----------|-----|
+| **npm / bundler** | `npm install @meoslabs/save-in-meos` then `import { initSaveButton } from '@meoslabs/save-in-meos'` |
+| **Script tag (CDN)** | Pin `https://unpkg.com/@meoslabs/save-in-meos@VERSION/dist/widget.iife.js` + `fonts.css` — see [`examples/cdn-demo.html`](examples/cdn-demo.html) |
+| **Programmatic only** | `import { buildMeosLink, buildImportIntentV1 } from '@meoslabs/save-in-meos'` — no widget CSS required |
+| **Local demo** | `npm run demo` then open `http://localhost:4173/demo?local=1` (stages `examples/vendor/` via `build:widget`) |
+
+CDN mirrors (auto-indexed from npm — no separate account):
+
+- **unpkg:** `https://unpkg.com/@meoslabs/save-in-meos@VERSION/dist/widget.iife.js`
+- **jsDelivr:** `https://cdn.jsdelivr.net/npm/@meoslabs/save-in-meos@VERSION/dist/widget.iife.js`
+
+Alias: `dist/save-in-meos.min.js` (identical minified IIFE).
+
+## Widget appearance
+
+The **save in meos** chip uses a **closed shadow root**. Integrators cannot change the label, font (Inconsolata), or logo SVG path. The logo is **vector** (from `assets/branding/meos-logo-charcoal-nostroke.svg`), rendered at **16px mark height** by default with the correct brand aspect ratio.
+
+| Customisable | Fixed (brand) |
+|--------------|---------------|
+| `theme: "auto" \| "light" \| "dark"` | Font family + weight |
+| `chipPreset: "default" \| "compact"` | Logo SVG path |
+| Chip height (28–40px), padding, radius | Arbitrary label text |
+| Logo mark height (11–16px) | Logo animation (static mark only) |
+
+### Chip presets
+
+Two presets only — pick size and label together:
+
+| Preset | Visible label | Use when | Height | Padding X | Radius |
+|--------|---------------|----------|--------|-----------|--------|
+| `default` | **save in meos** | Share rows (default) | 31px | 10px | 2px |
+| `compact` | **save** | Dense toolbars | 28px | 8px | 2px |
+
+`aria-label` is always **save in meos** (accessibility). Only the visible chip text shortens on `compact`.
+
+```ts
+initSaveButton("#meos-save-mount", {
+  u: location.href,
+  widgetId: "my-site",
+  theme: "dark",
+  chipPreset: "compact",
+})
+```
+
+Explicit `chip` fields override preset values. Prefer `chipPreset` over hand-rolled pixel values.
+
+**Theme:** `auto` follows OS `prefers-color-scheme`. Pin `light` or `dark` when your page theme differs from the OS.
+
+**Advanced shape via CSS on the mount host:**
+
+```css
+#meos-save-mount {
+  --meos-save-chip-height: 36px;
+  --meos-save-icon-size: 16px;
+}
+```
+
+**Live examples** (after `npm run demo`):
+
+| Demo | URL |
+|------|-----|
+| Blog post embed | `http://localhost:4173/demo.html?local=1` |
+| Theme + chip presets | `http://localhost:4173/theme-demo.html` |
+| CDN copy/paste snippet | `http://localhost:4173/cdn-demo.html` |
+
+See [`docs/INTEGRATOR.md`](docs/INTEGRATOR.md) for the full widget API.
+
+## Quick start — npm widget
+
+```ts
+import "@meoslabs/save-in-meos/fonts.css"
+import "@meoslabs/save-in-meos/widget.css"
+import { initSaveButton } from "@meoslabs/save-in-meos"
+
+initSaveButton("#meos-save-mount", {
+  u: "https://example.com/article",
+  widgetId: "my-site",
+})
+```
+
+## Quick start — script tag
+
+```html
+<link rel="stylesheet" href="https://unpkg.com/@meoslabs/save-in-meos@0.0.1/src/widget/fonts.css" />
+<div id="meos-save-mount"></div>
+<script src="https://unpkg.com/@meoslabs/save-in-meos@0.0.1/dist/widget.iife.js"></script>
+<script>
+  MeosSave.initSaveButton("#meos-save-mount", {
+    u: location.href,
+    widgetId: "my-site",
+  })
+</script>
+```
+
+## Quick start — build links programmatically
+
+```ts
+import {
+  buildMeosLink,
+  buildImportIntentV1,
+  decodeMeosLink,
+  type ImportIntentV1,
+} from "@meoslabs/save-in-meos"
+
+const intent = buildImportIntentV1({
+  u: "https://example.com/article",
+  t: "Optional selected quote",
+})
+
+const url = buildMeosLink(intent, "my-widget")
+const roundtrip = decodeMeosLink(url)
+```
+
+See [`docs/INTEGRATOR.md`](docs/INTEGRATOR.md) for tiers, branding rules, and Universal Links.
+
+## What is MDP?
+
+The **meos deeplink protocol** encodes an import intent — URL, optional quoted text, images — into a compact `https://meos.do/databox:import:…` link. Widget attribution travels in the `?w=` query param.
+
+| Tier | Use when |
+|------|----------|
+| **REF** | Page URL only |
+| **LITE** | URL + selected quote text |
+| **IMG** | URL + image URLs |
+| **FULL** | URL + structured blocks (advanced) |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run build:widget   # dist/widget.iife.js for CDN / script tag
+npm run demo           # build + serve examples (local widget demos)
+npm test
+npm run check:mdp          # contract + branding gates
+npm run check:public-scrub # no internal paths / secrets in docs
+npm run check:ci           # GitHub Actions workflow ratchet
+```
+
+## Publishing
+
+See [`docs/PUBLISHING.md`](docs/PUBLISHING.md) for the full checklist. Summary:
+
+1. **npm scope** — publish as `@meoslabs/save-in-meos` (or `@meos/…` if the org scope is available on npmjs.com)
+2. **First publish** — `npm login` → `npm publish --access public` (or GitHub Release → OIDC trusted publishing)
+3. **CDN** — unpkg/jsDelivr index the npm tarball automatically; pin `VERSION` in integrator HTML
+4. **Optional** — `meo cdn put dist/widget.iife.js` only if you also want a copy on `static.usemeos.com` (separate from npm mirrors)
+
+## Docs
+
+| Doc | Audience |
+|-----|----------|
+| [`docs/INTEGRATOR.md`](docs/INTEGRATOR.md) | Site owners embedding the widget |
+| [`docs/PUBLISHING.md`](docs/PUBLISHING.md) | Maintainers — npm publish + CI secrets |
+| [`docs/QA-MDP-SMOKE.md`](docs/QA-MDP-SMOKE.md) | Smoke-test this package before release |
+| [`docs/RELEASE-MDP-DEEPLINKS.md`](docs/RELEASE-MDP-DEEPLINKS.md) | App Links / Universal Links for integrators |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | meoslabs contributors |
+
+## Licence
+
+- **Code:** [MIT](LICENSE)
+- **Fonts:** Inconsolata [OFL-1.1](assets/fonts/inconsolata/OFL.txt) (bundled in the package)

package/assets/fonts/inconsolata/OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2006 The Inconsolata Project Authors
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/import-intent-v1.d.ts

@@ -0,0 +1,88 @@
+/**
+ * WHY: ImportIntentV1 is the codec SSOT for meos deeplink protocol (MDP).
+ *      Encode/decode for databox:import must live only in this package.
+ * WHAT: Types + encode/decode/buildMeosLink for `databox:import` URLs.
+ * HOW: Optimised wire schema (k: u|ut|i|f) → JSON → deflateRaw → base64url.
+ * WHERE: @meoslabs/save-in-meos — consumed by widget and meos clients.
+ * GUARDED: check-mdp-contract.ts golden fixtures in fixtures/mdp/.
+ */
+/** MDP contract version — semver pinned by golden fixture checkers. */
+export declare const MDP_CONTRACT_VERSION = "0.0.1";
+export type ImportIntentTier = "REF" | "LITE" | "IMG" | "FULL";
+/** Wire kind — compact tier discriminator inside the compressed blob. */
+export type ImportIntentKind = "u" | "ut" | "i" | "f";
+/** Canonical meos.do host for import deeplinks. */
+export declare const MEOS_DO_HOST = "meos.do";
+/** Colon-grammar resource for widget import (not facility bulk import). */
+export declare const DATABOX_IMPORT_RESOURCE = "databox:import";
+/** Maximum URL length before QR degradation (bytes, conservative for Level-M QR). */
+export declare const MDP_MAX_QR_URL_LENGTH = 2048;
+export interface ImportIntentV1 {
+    /** Schema version — always 1 for v1 codec. */
+    v: 1;
+    tier: ImportIntentTier;
+    /** Canonical content URL (REF/LITE/IMG/FULL). */
+    u: string;
+    /** Optional quoted text (LITE tier). */
+    t?: string;
+    /** Optional image URLs (IMG tier). */
+    images?: string[];
+    /**
+     * Widget attribution id — expressible via ?w= query param only.
+     * Never encoded into the compressed blob.
+     */
+    w?: string;
+    /** Optional PadSeed-shaped blocks (FULL tier). */
+    blocks?: unknown[];
+}
+/** Input for automatic tier selection before building an intent. */
+export interface ImportIntentInput {
+    u: string;
+    t?: string;
+    images?: string[];
+    blocks?: unknown[];
+}
+export declare class MdpEncodeError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class MdpDecodeError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Select the minimum encoding tier for the given content.
+ * REF — URL only; LITE — URL + distinct text; IMG — image URLs; FULL — blocks.
+ */
+export declare function selectImportTier(input: ImportIntentInput): ImportIntentTier;
+/** Build a typed ImportIntentV1 from loose widget input. */
+export declare function buildImportIntentV1(input: ImportIntentInput): ImportIntentV1;
+/**
+ * Encode ImportIntentV1 to a URL-safe payload segment (no host/path).
+ * Widget attribution (?w=) is never included in the blob.
+ */
+export declare function encodeImportIntentV1(intent: ImportIntentV1): string;
+/**
+ * Decode a databox:import payload segment back to ImportIntentV1.
+ * Does not parse ?w= — use decodeMeosLink for full URLs.
+ */
+export declare function decodeImportIntentV1(encoded: string): ImportIntentV1;
+export interface BuildMeosLinkOptions {
+    /** Override QR guard threshold (default MDP_MAX_QR_URL_LENGTH). */
+    maxUrlLength?: number;
+}
+/**
+ * Build full https://meos.do/databox:import:{encoded}?w={widgetId} URL.
+ * Degrades tier (IMG/FULL → LITE → REF) when the URL exceeds MDP_MAX_QR_URL_LENGTH.
+ * Widget id is query-only — never embedded in the compressed blob.
+ */
+export declare function buildMeosLink(intent: ImportIntentV1, widgetId?: string, options?: BuildMeosLinkOptions): string;
+/**
+ * Parse a meos.do import URL into ImportIntentV1.
+ * Accepts full URL or path-only `databox:import:…` segments.
+ * Widget attribution (?w=) is query-only and not merged into the intent.
+ */
+export declare function decodeMeosLink(url: string): ImportIntentV1;
+/** Read widget attribution from a meos.do import URL (?w= query param). */
+export declare function parseWidgetAttribution(url: string): string | undefined;
+//# sourceMappingURL=import-intent-v1.d.ts.map